MathGroup Archive 2010

[Date Index] [Thread Index] [Author Index]

Search the Archive

Re: Assertions in Mathematica?

  • To: mathgroup at
  • Subject: [mg113511] Re: Assertions in Mathematica?
  • From: "Sjoerd C. de Vries" <sjoerd.c.devries at>
  • Date: Sun, 31 Oct 2010 05:20:41 -0500 (EST)
  • References: <iaj4ob$n70$>

I'm afraid I have to strongly disagree with your opinion (rant) on
Mathematica's documentation. Though the docs are still not perfect, I
usually find within a few clicks what I'm looking for. I'm actually
rather fond of the documentation as it is now. The mixture of overview
pages, tutorials, function doc pages, crosslinks, and the fact that
doc pages are 'active' is very effective in my humble opinion. Access
to the docs in function browser, book, and doc centre form is nice as
well. Navigating around is extremely well done.

There are some lingering issues, such as the occasional lists of
"typical" option values listed on some doc pages instead of listing
*all* possible option values, and the use of the same option name in
completely different functions (like "Method") which often makes
looking up the specific option doc page useless. And indeed, some
options are only explained in the examples instead of on the formal
section of the doc page.

Peace -- Sjoerd

On Oct 31, 8:10 am, kj <no.em... at> wrote:
> Thank you all for your comments and suggestions.  The Hold* setting
> was indeed at the root of the problem.  Thanks also for the advice
> to become familiar with Mathematica's evaluation sequence.
> Regarding the docs, I still think it is Mathematica's worst feature,
> by far.  Given Mathematica's general excellence otherwise, and the
> fact that the main weaknesses of its documentation have not changed
> one iota for the ~20 years that I've used Mathematica, I conclude
> that these weaknesses are absolutely intentional.  In other words,
> more than just objecting to Mathematica's documentation, I object
> to its long-standing *philosophy* of documentation.
> This philosophy centers on the imperative to avoid formal specification
> as much as possible, and cover over this shocking omission with a
> few laconic examples.
> I don't know why the makers of Mathematica insist on this form of
> documentation.  Maybe they perceive formal specification as a threat
> to their intellectual property.  Or as a threat to the freedom of
> their future software development (since documenting a feature
> thoroughly may be interpreted by outside developers as a commitment
> to those details in future releases).  Or maybe they believe that
> users of Mathematica are too mentally feeble to read documentation
> that goes beyond a few brief (and hopefully "*neat*") examples.
> Or maybe all of the above.  Whatever the reason, the fact remains
> that, when it comes to the *content* of its documentation (as
> opposed to its presentation), Mathematica is third-rate at best,
> which is scandalous for software as expensive as it is.  Even
> open-source code like the standard Python or Perl libraries have
> documentation that, even though it is largely produced by unpaid
> volunteers, is vastly superior, content-wise, to Mathematica's.
> Mathematica's documentation is the reason why I never recommend
> Mathematica to anyone.  I just can't do it in good conscience, even
> though, in many other areas I consider Mathematica the gold standard.
> Yes, I use Mathematica myself, but that's because I've already
> "paid the price" of countless frustrating hours of blind trial and
> error to figure out what the documentation omits and thus reach a
> minimal level of proficiency with it.  IOW for me the worst part
> is in the past.  I'd gladly give up using Mathematica for good in
> exchange for getting back all that misspent time.
> ~kj

  • Prev by Date: Re: It would be nice to have DiagonalMatrix accept a matrix as building
  • Next by Date: Re: Assertions in Mathematica?
  • Previous by thread: Re: Assertions in Mathematica?
  • Next by thread: Re: Assertions in Mathematica?