Re: Assertions in Mathematica?
- To: mathgroup at smc.vnet.net
- Subject: [mg113603] Re: Assertions in Mathematica?
- From: David Bailey <dave at removedbailey.co.uk>
- Date: Thu, 4 Nov 2010 04:00:04 -0500 (EST)
- References: <iaj4ob$n70$1@smc.vnet.net> <iajftk$qas$1@smc.vnet.net> <iaonnh$jmh$1@smc.vnet.net>
On 02/11/10 10:04, kj wrote: > 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 > I have been a software developer for over 30 years, and I must say, I use formal documentation as a last resort! Here are some of the reasons why: 1) It is rare to wish to use a function or command in its full generality. A few well chosen examples may cover 95% of the cases, and are obviously much easier to access. The Mathematica documentation always gives access to the syntax of the rarer cases, so nothing is lost really. 2) Formal documentation seems to squeeze out facts that don't fit the schema. For example, FullSimplify uses some form of search process that is terminated by a time constraint - a formal spec for such a function would be very hard to write. 3) Many functions, such as Plot, call other functions that could, in principle have side effects that could introduce all types of complications. It is far better to leave the question of just how many function calls are made, as indeterminate. 4) Some functions - such as Integrate - do as best they can. Any formal specification as to what Integrate could or could not do, would be pretty mindless. 5) A lot of formal documentation only works because those who read it, have access to a lot of informal information and/or example programs. In addition, it is important to remember that Mathematica is sold to many people who have only a limited experience of programming - the kind of documentation you prefer would be very intimidating. David Bailey http://www.dbaileyconsultancy.co.uk