[Cocoon Wiki] New: CocoonDocumentationSystemHowTo

[do...@cocoon.apache.org]

   Date: 2005-01-27T05:30:45
   Editor: ReinhardPoetz
   Wiki: Cocoon Wiki
   Page: CocoonDocumentationSystemHowTo
   URL: http://wiki.apache.org/cocoon/CocoonDocumentationSystemHowTo

   how to write docs for the new documentation system

New Page:

= 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.

The current status of the new docs can be found at 

 * http://brutus.apache.org/docs/build/cocoon-doco-2-2/
 * http://brutus.apache.org/docs/build/cocoon-doco-global/

== 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 you 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 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 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.