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
- References:
- Re: annoying documentation in 6 (rant)
- From: David Bailey <dave@Remove_Thisdbailey.co.uk>
- Re: annoying documentation in 6 (rant)