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)