Here's a draft of my proposal for a documentation plan, from the user/website visitor point of view. – BertrandDelacretaz

See also

The idea is to use this table as our overall documentation plan, showing where we stand in each category. Maybe the table should rather show minimal info, completed by details down the "documentation plan" page.

Doc category



Doc types



Help wanted



Describe Cocoon at a high level: purpose, architecture, component types, usage examples, strengths and weaknesses, similar systems.

Doc authors who are not necessarily developers


CVS, docs directories

Some docs exist, need to be refactored

*Refactoring *TBD


Used by someone who, based on the Concepts, decides to try or use Cocoon.

Doc authors who are not necessarily developers


CVS, docs directories

Many docs exist, navigation needs to be improved


Reference [

Detailed information on every component, in unix manpage style: one page for each component, always with the same document sections, including a "see also" section.

Must be written by developers (at least in draft form) when components are created. Might be revised by doc authors later on.


Stored (as xxx-manpage.xml files) along with the component source code files and inside Blocks, partially generated from javadoc tags that complete the xxx-manpage.xml files.#2]

Extensive refactoring needed



Scratchpad for draft documents and/or annotations to existing docs

Written by anyone who cares to contribute



Growing steadily


Reader's comments

on cocoon-docs, Andy Lewis says: There are multiple types of reference docs to be accomodated though. The man pages (need a good name for these, or just agree to adopt the Unix term), JavaDocs, etc. Also keep in mind that if this really follows the Unix model, there may be man pages for things other than components, such as file formats, etc. Possibly a man page with a quick summary of the sitemap syntax and usage - who knows. Point being, it could be a bit broader in application.

Do we need one user and one developer manpage for some or all components?

  • No labels