MathGroup Archive 2007

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

Search the Archive

Re: Re: annoying documentation in 6 (rant)

  • To: mathgroup at smc.vnet.net
  • Subject: [mg79076] Re: [mg79068] Re: annoying documentation in 6 (rant)
  • From: Murray Eisenberg <murray at math.umass.edu>
  • Date: Wed, 18 Jul 2007 02:51:39 -0400 (EDT)
  • Organization: Mathematics & Statistics, Univ. of Mass./Amherst
  • References: <f77j9r$c9p$1@smc.vnet.net> <19356212.1184479716385.JavaMail.root@m35> <f7f34s$od7$1@smc.vnet.net> <200707170728.DAA27254@smc.vnet.net>
  • Reply-to: murray at math.umass.edu

Mathematica docs have, as I recall, never been complete, at least to the 
point of completeness, clarity, and unambiguity.

For example, in Mathematica 5.2 Help Browser, look up TableHeadings. 
See if you can discern from the /description/ which of the two arguments 
of TableHeadings labels the rows and which the columns.  Of course 
eventually one of the Further Examples under the linked topic TableForm 
indicates that the first labels the rows, the second the columns.

But I don't think there is a more general explanation of a more general 
principle or concept that would allow one to deduce that from the 
descriptive documentation (as opposed to the examples).

I seem to recall encountering a similar problem with 6.0, for which 
arguments of Alignment affects rows and which affects columns.

The more general problem -- aside from the fact that examples are often 
used in place of definitive statements of semantics -- in these cases 
seems to be a lack of clarification of dimensionality terminology.

I must admit that different people, and the same person in different 
situations or at different times, learn and understand things 
differently: sometimes the definitive, complete, unambiguous statement 
is what's needed; often just enough examples suffice to allow one to 
come to conceptualize and internalize such a statement for oneself.

David Bailey wrote:
> DrMajorBob wrote:
>> It's not what I'd call entirely obvious, but...
> 
> Maybe WRI should employ you to write their documentation!
> 
> Seriously, though, without a book for 6.0, the help topics absolutely 
> must be authoritative and complete. If I had written the code behind 
> ColorData, I would feel seriously miffed that it was documented in such 
> an off-hand way.
> 
> A lot of the newly documented functionality has the feel of an 
> introductory overview. If you are experienced with Mathematica, it is 
> possible to hack your way to an understanding with some experimentation, 
> but that is certainly not good enough for beginners.
> 
> Here is another typical quote from the page ref/format/HTML (discussing 
> the exporting of HTML):
> 
> Export["file.html",{Subscript[elem, 1]->Subscript[expr, 
> 1],Subscript[elem, 2]->Subscript[expr, 2],\[Ellipsis]},"Rules"] uses 
> rules to specify the elements to be exported.
> 
> That is documentation, Microsoft-style!
> 
> Sometimes the purpose of a page is hard to discern. For example: 
> ref/format/GIF
> 
> You reach this page from Export/Import. If you want to export/import 
> GIF's it may be useful to learn something about the nature of a GIF 
> image. If you know how GIF's work, the introductory text confirms what 
> you already know - in a very legal, prissy sort of way. However a 
> beginner will be unlikely to discover whether his image would be better 
> exported as a GIF or a JPEG (say).
> 
> I suspect Stephen Wolfram wrote a lot of the earlier Mathematica 
> book(s), and he obviously had a big say in the entire contents. As a 
> result, these books were very easy to read (as well as being good for 
> the biceps).
> 
> Ideally, Stephen would clone himself and solve the problem, but as an 
> alternative, maybe WRI should invite some newbies to spend a week with 
> them and ask them to explore various topics - such as Export - using the 
> help system, and observe all their problems.
> 
> David Bailey
> http://www.dbaileyconsultancy.co.uk
> 

-- 
Murray Eisenberg                     murray at math.umass.edu
Mathematics & Statistics Dept.
Lederle Graduate Research Tower      phone 413 549-1020 (H)
University of Massachusetts                413 545-2859 (W)
710 North Pleasant Street            fax   413 545-1801
Amherst, MA 01003-9305


  • Prev by Date: Re: Re: integration of piecewise convex bivariate function with 6 parameters
  • Next by Date: Controlling the Appearance of Locators in Manipulate Statements
  • Previous by thread: Re: annoying documentation in 6 (rant)
  • Next by thread: Re: Re: annoying documentation in 6 (rant)