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

Re: Documentation - what is the big secret?

• To: mathgroup at smc.vnet.net
• Subject: [mg87567] Re: Documentation - what is the big secret?
• From: "Dr. David Kirkby" <david.kirkby at onetel.net>
• Date: Sun, 13 Apr 2008 03:32:02 -0400 (EDT)
• References: <fti3v2$oho$1@smc.vnet.net> <ftkbce$b8b$1@smc.vnet.net> <ftq547$ei$1@smc.vnet.net>

David Reiss wrote:
> I basically agree with David here.  I think that there is indeed a
> style of working that corresponds to the workflow in Workbench.  And I
> suspect that there are many who like to work with it.  However My
> approach to Mathematica programming (and I have done a **lot** of it
> over the years) is to code in notebooks and save to packages.  So it
> does make sense to include documentation tools inside of Workbench as
> WRI is in the process of doing.  

But this needs to be in addition to documenting the format of the 
documentation.

<snip>

> such tools in the next version of http://www.scientificarts.com/worklife/.
<snip>

> The way that I have created these has been to reverse engineer the
> examples that are included with Mathematica:

But it should not be necessary to reverse engineer files, as others have 
said.

I assume there are internal documents in Wolfram Research detailing how 
to write documentation. Perhaps WRI could clean them up a bit and 
release them. One the whole, Mathematica's documentation is excellent, 
but it really seems to be let down in this area. I can think of no other 
area where the documentation is so poor, although there might be areas I 
don't know about.

<snip>
> have devoted so far to this aspect of http://www.scientificarts.com/worklife=
<snip>
> of tools for Documenting within http://www.scientificarts.com/worklife/
<snip>
> follow-on releases of http://www.scientificarts.com/worklife/.  So,

<snip>
>   Frankly, the more folks who try and buy http://www.scientificarts.com/work=
> life/,
<snip>
> Trial Version at:
> http://scientificarts.com/worklife/

Does it really need 6 links to http://scientificarts.com/worklife/ in 
one message? I understand you want to sell it, but that amount of 
spamming just puts people off.