New Cocoon documentation system: How to contribute?

This is a step-by-step explanation on how to contribute to the new Cocoon documentation. If you want some more background about the documentation system in the background, checkout the wiki page explaning the CocoonDocumentationSystem. If you have questions, feel free to ask on cocoon-dev or cocoon-users list.

Step 1: Identifiy, what you want to do?

Cocoon already has a lot of documents, some are good, some need to be improved or updated. Find a list of all docs in 2.1 at 22NewDocuments. Look for a document you want to work on and add your name so that other people know that this is 'yours'. Verify the content.

Also there are a lot of Wiki pages that are worth to be added to our official documentation. If you find a page, add a note at the top of the page that you're working on moving it to our official documentation.

22NewDocumentsGeneration shows where the current version of the docs is available.

Step 2: SVN checkout

The second step is checking out the Forrest repositories. Find them in our SVN at http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/. If you are new to SVN find infos at http://cocoon.apache.org/community/contrib.html#Subversion+Usage+Precis.

Step 3: Create a new document

(If you're are working on an existing document, you can of course skip this step.)

Find all documents in the directory src/documentation/content/xdocs and create a new directory. This directory contains all files that are needed to generate the final document:

 ./content_en.html .......................... the content of the page as HTML4 document
 ./files/* .................................. images and attachements

Step 4: Write your document - use your favorite HTML editor

Use e.g. Mozilla composer to edit ./content_en.html. Although it is HTML and you could do whatever HTML4 allows, you should concentrate on structural elements like h1, h2, h3, ul, ol, img, p and a. When the web application that will enable editing via browser, the documents will be transformed into XML docuements that are based on a subset of XHTML.

If you want to add images or e.g. ZIP attachements, put them into the ./files-directory.

Step 5 (You are not a Cocoon committer): Add your document to Bugzilla

Use bugzilla (more info at http://cocoon.apache.org/2.1/howto/howto-bugzilla.html) and add your document there. Select documentation as component type. Please also make a proposal where you would add the document in the hierarchy (see src/documentation/content/site.xml).

Step 5 (You are a Cocoon committer): Checkin the document yourself

Check-in the document yourself and don't forget to add it to src/documentation/content/site.xml. If you want to re-generate the docs, use Forrestbot at brutus.apache.org. Contact ReinhardPoetz or DavidCrossley to get the exact URL, the username and the password. As an alternative, you can wait for the next periodical update of the website.