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