The thread on the PD documentation project seems to have
died, and I presume that it is because no one is really
sure how to go about it, or no one is willing to commit to
actually steer it.
I am willing to put myself forward for some of the work,
but as with anyone, my time is limited. Unless someone has
a better idea, I would like to propose this following chain
of actions.
1) discussion on list of the break up and format of the
documentation;
what outputs should the documentation be
delivered as (HTML, RTF?, others?);
how should the documentation be indexed, markup'ed and
stored (docbook? XML?)
what volumes/books/chapters should the documentation
divided into [e.g.:
book: PD
chapter: pd syntax/principles (as per existing docs)
chapter: object list (as per Max reference manual)
book: GEM
chapters...
book: Source Code info
chapter: how PD works
chapter: how to compile PD
subsection: how to solve the compilation problems
in RH 7.x
chapter: how to program externals
book: specific subjects in PD (kind of like the
Csound book)
etc. ]
what existing documentation should be
adapted/modified/recycled to fit in above
2) division of the work between volunteers as:
- editors, coordinating the documentation project
- documentation specialists (for lack of a better term) who
will supervise and adapt how the documentation is stored,
modified, maintained, version'ed, etc.
- writers, who will write the actual documentation and
reference
In a dream world, I would personally like to see a
centrally maintained, always up-to-date, moderated on-line
system, through which submissions can be made (with online
forms, say); it would be beneficial to facilitate inline
graphics (such as jpeg) for diagrams and screenshots; there
should be automated links to object names and such; and
there should be a way for people to annotate or add
corrections online (and credit them of course.)
I have had a look at existing documentation projects and
systems, and so far I haven't really found anything that
does everything in one package. However it is obvious that
XML should be the underlying format for storing the content
of the documentation, although I don't see what the best
way is to do that.
- martin