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

See also http://marc.theaimsgroup.com/?l=xml-cocoon-docs&m=103760965422815&w=2

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

Goals/Tools

Authors

Doc types

Storage

Status

Help wanted

Concepts

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

Doc authors who are not necessarily developers

xdocs

CVS, docs directories

Some docs exist, need to be refactored

*Refactoring *TBD

Tutorials

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

Doc authors who are not necessarily developers

tutorial,howto,faq

CVS, docs directories

Many docs exist, navigation needs to be improved

*TBD

Reference #1

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.

manpage

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

*TBD

Wiki

Scratchpad for draft documents and/or annotations to existing docs

Written by anyone who cares to contribute

free-form

CocoonDocoWiki

Growing steadily

*TBD

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?

CocoonDocsPlan (last edited 2009-09-20 23:41:12 by localhost)