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
