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>