Look around and find something whose documentation you like,
and copy that concept.
Do you like the mathematica "bible" and its on-line version?
Do you like the commercial macsyma stuff?
Do you like documentation for (say) Word or Excel?
I think Apple stuff used to, maybe still does, come with
books called "before you begin...".
It may also help to have targeted audiences.
e.g.
education/ k-12; college/ more.
application / finance; physics; /etc.
I still find the idea of having one person write a program
and another one "document" it 20 or 30 years later to be
bizarre. But that is what we have as a task.
RJF
C Y wrote:
> Well, since there is some agreement that a documentation effort is a
> good idea, I guess I might as well venture to throw out some specific
> questions/ideas and see what everyone's got in mind.
>
> Question 1: Structure of Documentation - i.e., what do we need?
>
> What we currently have, as I understand it, is the online help in
> maxima itself, the reference manual, and a few other misc. introductory
> documents. Here are my thoughts on what might be a good way to focus:
>
> 1) Tutorial/Users Manual
>
> The limitation I think most people have when they look at Maxima
> initially is just having no clue where to start, and even after they
> start not being able to figure out how to do any particular thing
> without a fair bit of effort. This document should be structured in a
> task oriented manner - i.e., how to make Maxima do specific types of
> things. Say for example someone wants to perform a series of matrix
> operations - the tutorial should take a problem based approach, showing
> which tools can do which job, the exact syntax used, what the pitfalls
> of a particular approach might be, etc.
>
> 2) The Reference Manual
>
> This can build off of the manual we already have, with the main
> effort being to keep it up to date for new packages, fixes, etc. and to
> test the behavior of what's already described in the manual, making
> sure everything is accurate, clearing up confusing parts, etc.
>
> 3) Programmer's Manual
>
> This one I have fewer concrete ideas about, except that it should
> define a coding standard. Richard has had some good suggestions about
> principles to adhere to when working on Maxima - those should
> definitely be in here. Also, this would be the place to maybe start on
> an effort to map the guts of Maxima - what depends on what, how various
> parts work, etc.
>
>
>
> Question 2: What do we use?
>
> Docbook seems to be the standard for documentation these days, but I
> don't think it has much in the way of mathmatical markup capability.
> LaTeX can handle almost any math formatting, but is not the standard
> documentation format. However, it has BibTeX and lots of nifty
> scientific writing features. Currently we don't need graphical markup
> in Maxima, since everything is ascii text, so Docbook can probably
> serve our current needs. Anyone with experience in this department? I
> have no idea what would be best.
>
>
> Question 3: Documentation's relation to Maxima updates
>
> If and when we get the documentation to a point where it makes sense
> to do so, should we have some sort of policy that before any release
> all the changes need to be updated in the documentation?
>
>
> Those are the major points I have come up with thus far - comments
> please. This is by no means a definite proposal or statement of what
> we should do - this is just something to get discussion going.
>
> CY
>
> __________________________________________________
> Do You Yahoo!?
> Listen to your Yahoo! Mail messages from any phone.
> http://phone.yahoo.com
> _______________________________________________
> Maxima mailing list
> Maxima@www.math.utexas.edu
> http://www.math.utexas.edu/mailman/listinfo/maxima
>