cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hepabolu <hepab...@gmail.com>
Subject [RT] The Cocoon Handbook - a Hackathon approach
Date Mon, 11 Oct 2004 14:38:38 GMT
Guys and Gals,

I'll write this up as a summary of the discussion on the Cocoon
documentation we had with a bunch of people on the Hackathon. Should
anyone of the attendants feel I left something out or described it the
wrong way, do reply and correct.

The discussion revolved about two main issues: content and technical
infrastructure.

Content

The main documentation topics are (in random order):
- component reference/feature list
- user documentation/user guides
- tutorials or recipes or use cases on how to use Cocoon

We believe that documenting components through JavaDocs is the easiest
thing to do for the moment. So we kindly ask each component developer
to spend some time on improving the JavaDoc documentation (a little
bit at a time) by adding a small sample or a few lines that describe
the overall functionality.

The other points are more or less covered in the
http://wiki.apache.org/cocoon/Cocoon215TOC which will be the starting
point for the current  restructure for now.

Technical infrastructure

Although everyone agrees that ultimately the existing Cocoon
documentation should be updated/replaced, we feel that going through
the motions of patching xdocs and generating the full docs website
takes too much time and puts up too high a barrier to quickly add and
improve the documentation.
For now we will stick to the wiki and try to build a ToC starting from
the http://wiki.apache.org/cocoon/Cocoon215TOC. This ToC is NOT final.
It is merely a structure to add information to and the main objective
now is to add links to the ToC that point to either existing pages
(which are reviewed and approved to the best of our knowledge) or to
new pages that add missing information or provide updated information
for the current Cocoon version.

The steps will be:

- replace the static text in the Cocoon215TOC with links
- extend the ToC with missing elements
- if there are links to external information or volatile links, the
author of the text will be asked permission to integrate the
information in the Cocoon Wiki.
- if there is relevant information in the mailing lists, the
information is rewritten into running text and a post is put on the
mailing list to inform the original authors and give them time to
object.

-- 
Bye, helma

Mime
View raw message