Re: annoying documentation in 6 (rant)
- To: mathgroup at smc.vnet.net
- Subject: [mg79091] Re: annoying documentation in 6 (rant)
- From: "Kevin J. McCann" <kjm at KevinMcCann.com>
- Date: Wed, 18 Jul 2007 02:59:27 -0400 (EDT)
- References: <f77j9r$c9p$1@smc.vnet.net> <19356212.1184479716385.JavaMail.root@m35> <f7f34s$od7$1@smc.vnet.net> <f7hrqb$s2i$1@smc.vnet.net>
And let's not forget the nearly complete lack of documentation on
StyleSheets. If it weren't for David Park's very helpful introductory
tutorial, I would be completely lost.
Kevin
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
>