Services & ResourcesWolfram ForumsMathGroup Archive

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

Re: Assertions in Mathematica?

• To: mathgroup at smc.vnet.net
• Subject: [mg113565] Re: Assertions in Mathematica?
• From: kj <no.email at please.post>
• Date: Tue, 2 Nov 2010 05:04:33 -0500 (EST)
• References: <iaj4ob$n70$1@smc.vnet.net> <iajftk$qas$1@smc.vnet.net>

In <iajftk$qas$1 at smc.vnet.net> "Sjoerd C. de Vries" <sjoerd.c.devries at gmail.com> writes:

>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.

I guess you did not read where I wrote

>> 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.

All the things you list as pluses fall under "presentation", not
content.

Do you understand what I mean by "formal specification"? Don't you
see that Mathematica's documentation avoids formal specification
as much as possible?  Don't you see that this documentation forces
readers to *guess* at the formal specification on the basis of a
few examples, and unbounded amounts of trial-and-error? If you
don't understand these points, then of course my criticism of
Mathematica's documentation won't make any sense to you.

In response to the attack on Unix man pages in a different response,
I disagree.  The Unix man pages are, on the whole, incredibly useful
to the experienced programmer.  In fact, that's exactly what I
think Mathematica is missing, a proper *detailed* reference manual,
with full, explicit specification of what every function does, as
opposed to what it has now, which is, at best, a lightweight user's
guide (trying to pass itself off as a reference manual).  There's
nothing wrong with a user's guide; it definitely has a place in
the whole documentation library.  But it is not even close to being
enough.  As far as I know there has never been an attempt to make
a Mathematica reference manual available to the public (although
I'm sure Wolfram's developers have access to that level of
documentation internally; it would be impossible for them to do
their work without it).

Software developers need formal specifications to do their work.
That's why formal APIs and formal protocols (HTTP, SMTP, etc.)
exist.  It would be impossible to implement a web browser or a mail
reader without such *exhaustive* formal specifications, where
nothing is left for the reader to guess over.  By the same token,
it is impossible to write solid code in Mathematica without formal
specifications that say *exactly* what each Mathematica function
does.  This lack of formal specification is particularly egregious
in the area of research-oriented programming, where the wrong
"educated guess" on the part of the programmer over what the
Mathematica code is doing can eventually lead to the publication
of erroneous results.

~kj

• Follow-Ups:
  • Re: Assertions in Mathematica?
    • From: Andrzej Kozlowski <akoz@mimuw.edu.pl>