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 [ |
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?