C Y wrote:
>
> --- Richard Fateman <fateman@cs.berkeley.edu> wrote:
> > Suggestions:
> > The manual might start with:
> > Choose 1. Maxima is installed on my computer. How do I use it? Go
> > to
> > chapter N
> > 2. How do I get Maxima? Go to "Installation Guide"
> > 3. What is Maxima anyway? Continue reading here..
>
> Good point, but I think normally those questions are posed in a README
> file, not in the manual itself. The Chapter headings in the table of
> contents (if properly named) should pretty much handle that
> automatically as far as the Manual is concerned.
I don't know if it could be worth but as someone mentioned earlier in
the list a good starting point would be to copy some other documentation
efforts of open source programs
I use lyx and everyone agrees in the excellent documentation that
accompanies this nice piece of software. They have structured the help
documentation in several documents. A maxima replicant outline could be:
o Introduction. General recommendations on how to use the documentation
and what it is expected to find through the other documents:
o Tutorial. How to start with maxima, solving simple maths,
miscellaneous. This could be C.Y section 4, Basics, plus a more general
overview on other capabilities of maxima, a complete session with
graphics and text output, and the basic input using, etc, ...including
many of the examples that comes in maxima manual would be worth. This
document is the key to retain many users because it must provide a full
picture of what maxima can do by examples.
o User's guide. A fully comprehensive guide to maxima describing deeply:
maxima setup, supporting applications, i.e, graphics stuff, maxima
basics, maxima and lisp,
o Extended Features: perhaps C.Y part II, sections 12 and 13 about
current external packages and modules, how to use them, description of
the main packages, ...,
o Customization: how to configure maxima, how to create new packages or
modules,
o Reference Manual. The full reference to the maxima commands.
o FAQ
o Known bugs
o Lisp Configuration or some aspects related to different lisps
The idea is to start from a very basic and quick guide to learn the
basics by examples, Tutorial, and to progress to a more deeply knowledge
by increasing
the details and difficulty in a progressively way by using the suer's
guide and finally the extended, customization and reference manuals.
Anyway, this is a very nice start and most of the parts of the puzzle
are there, so keep on your good work !!
Regards
Oscar
---
http://www.iit.upco.es/~oscar
The human mind treats a new idea the way the body treats a strange
protein -- it rejects it.
-- P. Medawar