[Docs] General Planning

[Berin Loritsch <bl...@apache.org>]

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: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org