[PD] PD Documentation project

[Dupras, Martin]

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