Re: annoying documentation in 6 (rant)
- To: mathgroup at smc.vnet.net
- Subject: [mg79009] Re: annoying documentation in 6 (rant)
- From: David Bailey <dave at Remove_Thisdbailey.co.uk>
- Date: Sun, 15 Jul 2007 01:14:35 -0400 (EDT)
- References: <f77j9r$c9p$1@smc.vnet.net>
Murray Eisenberg wrote: > An example of how "hype" has intruded into the documentation in > Mathematica 6 is the paragraph at the top of the page > guide/NewIn60AlphabeticalListing: > > By far the largest release since Version 1.0 in 1988, Version 6.0 adds > a remarkable breadth of new functionality. As well as introducing > several major new fundamental concepts, it adds nearly a thousand new > functions, and significantly enhances a large fraction of all existing > Mathematica functions. > > I have no objection to the assertion that Mathematica 6.0 is "by far the > largest release since Version 1.0", or that it "adds nearly a thousand > new functions", or that it "significantly enhances a large fraction of > all existing Mathematica functions." > > But... Must it say "remarkable breadth of new functionality"? Must > there be the sledge hammer of "major new fundamental concepts"? > > Is it really necessary in the documentation explicitly to remind users > as to how wonderful Mathematica, and Mathematica 6.0 in particular, is? > > Is this sort of stuff aimed at making folks feel good about their > purchase and use of Mathematica 6.0? Or, since the same documentation > appears on the Wolfram web site, does the problem arise from confounding > advertising with documentation? > > Sorry for the rant. > Let me add slightly to your rant! I don't like documentation - such as that for the new ColorData function which feels (and is) vague. This contains phrases such as: "Typical collections of schemes include:" (followed by a list which is certainly incomplete because it doesn't include "Legacy", which you need to translate the old colour scheme! Furthermore, can someone tell me what 'collections' refers to in this context? This style of documentation suggests that the author only included those options he happened to remember as he wrote the page, and is particularly unfortunate now that so many arguments and option names are specified as strings - so it isn't easy to find all the possibilities. Much of the explanation of this function only happens via the examples, and goodness knows how many extra possibilities have been coded but never documented! David Bailey http://www.dbaileyconsultancy.co.uk