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

Re: Assertions in Mathematica?

• To: mathgroup at smc.vnet.net
• Subject: [mg113526] Re: Assertions in Mathematica?
• From: David Bailey <dave at removedbailey.co.uk>
• Date: Mon, 1 Nov 2010 05:00:45 -0500 (EST)
• References: <iaj4ob$n70$1@smc.vnet.net> <iajgs3$qt7$1@smc.vnet.net>

On 31/10/10 10:36, Nasser M. Abbasi wrote:
> On 10/31/2010 12:10 AM, kj wrote:
> ...
>
> Can I also join in the rant about the documentations? :)
>
> What I like to see more in documentations:
>
> 1. more examples, and more examples, and yet more examples.
> 2. more description, do not be too terse. Many times, a command will
> show one small example, and its output, with little words or description
> to help someone to understand it.
>
> Also, Documentation should have more tutorials showing how to combine
> many commands together.
>
> I also think the documentation should be written not by the developers
> themselves, but by non-programmers.
>
> Because if the programmer writes the documentation of the software they
> know, they think something is 'obvious', and so they will short change
> the documentation.
>
> I think the Mathematica documentation seems to be written by the same
> engineers who work on Mathematica itself, and these are very smart
> developers to start with, and they think every one is at their level of
> knowledge of Mathematica (subconsciously), so they might not describe
> the command fully.
>
> So please add more examples and more details to the documentations. More
> is always better when it comes to help pages. Do not be like the unix
> man pages ;)

I'd broadly agree with that, but maybe put it a different way.

I think Mathematica documentation is not as good as it was several 
versions back when it was written in the famous tome (door stop)!

It would seem that Stephen Wolfram wrote this book personally, and it 
always seemed to me that he took great effort to make sure that each 
example was complicated enough to show what it was meant to show, but 
not unnecessarily complicated. Now the documentation can be patchy. Part 
of the problem is that WRI has a formal documentation template. One 
might think this would help, but in practice the effect is that the 
documenter fills in each section and doesn't stop to think if the 
relevant information has been conveyed overall. Read the Import[] or 
Export[] documentation to get a feel for what I mean!

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