Services & ResourcesWolfram ForumsMathGroup Archive

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

Re: Mathematica 7.0.1.0 and some General Comments

• To: mathgroup at smc.vnet.net
• Subject: [mg97262] Re: Mathematica 7.0.1.0 and some General Comments
• From: David Bailey <dave at removedbailey.co.uk>
• Date: Mon, 9 Mar 2009 01:07:39 -0500 (EST)
• References: <goqphr$lt2$1@smc.vnet.net>

David Park wrote:

> One other requirement to make a breakthrough is the necessity of anyone to
> be able to freely read an active and dynamic Mathematica notebook. It should
> be something like the model of the free Acrobat reader. PlayerPro would do
> the job but it is too expensive. I know there are problems here. I wouldn't
> care if the reader couldn't print or save the notebook. Perhaps dynamic
> InputFields could be limited in the total number of typed characters for the
> notebook. Anyway, if it is so easy to hack PlayerPro in a usable way, why
> don't some people just pay the $200 and do it? A free general Mathematica
> reader would do more to smash the old technology and advertise the power of
> Mathematica notebooks than anything else I can think of.
> 

Just to concentrate on one of your issues - that of documentation, I am 
sure that the people at WRI who decided to move to paperless 
documentation used arguments such as:

1) We can redirect all the effort that went into a finished book into 
providing more and better information.

2) Virtual documentation is so much better because it can be updated so 
easily.

In reality, what has happened is a retreat from quality documentation in 
the belief that whatever is wrong can always be fixed at the next pass. 
Thus for example, we find the following phrase in the help for Import:

"Types of elements typically supported include:"

What does the word "typically" mean? Presumably it means that the author 
could not be bothered to obtain a definitive list - even as of some 
particular version. To make matters worse, since the elements are 
specified as strings, there is absolutely no way to discover the 
elements that the author happened to forget (or, indeed the 
corresponding functionality!).

The documentation of new or enhanced features is littered with 
phraseology of this sort. Compare, for example, the documentation of 
'Import' with an old favourite like 'Map'.

Furthermore, I don't think people learn a new package well by just 
invoking the help system. The help system is more suitable for people 
with at least some experience, who know what they want to look up.

I learned Mathematica from the old book. People laughed at it because of 
its size, but it gave me a clear idea as to what was important, and what 
to read first - and of the overall scope of the software. As an example, 
I doubt if any newish Mathematica users think they need a clear 
understanding of the frontend/kernel architechture - so they never read 
about this, and suffer from a variety of misconceptions as a result. A 
book spoon-feeds the information in roughly the right order.

David Bailey
http://www.dbaileyconsultancy.co.uk

• Follow-Ups:
  • Re: Re: Mathematica 7.0.1.0 and some General Comments
    • From: George Woodrow III <georgevw3@mac.com>