I will not be able to do all the documentation, so I
want to provide an outline for all the documentation
we will need. Those who are interested, please make
your contributions and the committers will add or
patch the documentation.
The 1st order of business is the _requirement_ of both
printable and browsable documentation. The Printable
docs will be a very simple markup, with minimal graphics.
They will have *no* navigation links. Browsable docs
will be the current complex XML.apache.org format (which
really needs revisiting). The Browsable docs will all
have an extra link to view the printable version.
We need 3 documentation tracks:
1) Installation and Configuration
2) Using Cocoon (creating your own webapps)
3) Developing Cocoon (maintaining Cocoon/Cocoon architecture).
I will post outlines for each of the different tracks,
with general information about what they should need.
I propose that for new documentation we use DocBook format.
You will see examples in Avalon CVS (the Developing with
Avalon documentation). The Stylesheets in the Avalon CVS
can be adapted for Cocoon.
The URI space will be planned as such:
cocoon2/ Welcome page and general overview--links to mailing
lists, CVS, and distributions
cocoon2/api The JavaDocs for Cocoon
cocoon2/authors The list of author bios (linked from the documentation
pages--like on Jakarta Avalon site)
cocoon2/installing The installation and configuration documentation
cocoon2/userdocs The user documentation (i.e. HowTo write your own
webapps with Cocoon)
cocoon2/developing The developer's docs on the architecture and design
of Cocoon.
There should be 4 FAQ documents:
1) cocoon2/faq.html Questions about Cocoon in general (what is it? why
was it built? etc).
2) cocoon2/installing/faq.html Questions about installing and configuring
Cocoon (XYZ doesn't work, what should I do?)
3) cocoon2/userdocs/faq.html Questions about how to do something in Cocoon
(I need to serialize XML from a database, how?)
4) cocoon2/developing/faq.html Questions about maintaining Cocoon
(I've spotted a bug and have a fix, how do I
get it committed? Why is XYZ ThreadSafe?)
This is the initial documentation planning, I will post individual outlines
for each documentation track later today.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
