Re: annoying documentation in 6 (rant)
- To: mathgroup at smc.vnet.net
- Subject: [mg79068] Re: annoying documentation in 6 (rant)
- From: David Bailey <dave at Remove_Thisdbailey.co.uk>
- Date: Tue, 17 Jul 2007 03:28:42 -0400 (EDT)
- References: <f77j9r$c9p$1@smc.vnet.net> <19356212.1184479716385.JavaMail.root@m35> <f7f34s$od7$1@smc.vnet.net>
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
- Follow-Ups:
- Re: Re: annoying documentation in 6 (rant)
- From: Murray Eisenberg <murray@math.umass.edu>
- Re: Re: annoying documentation in 6 (rant)
- From: Murray Eisenberg <murray@math.umass.edu>
- Re: Re: annoying documentation in 6 (rant)