!!! NOTE: This document is a summary of CocoonDocumentationSystem and maintained by ReinhardPoetz. Please add your comments there !!!


Motivation (or problems I want to solve)

I don't think that a technical solution will directly lead to better docs. I just think that making the doc authoring process easier will invite much more people to help out.

Architecture

Overview

    +------------------+              +------------------+
    |SVN REPOSITORY    |              |  COCOON WEBSITE  |
    | +--------------+ |period. update| +--------------+ |
    | |global docs   |-+--------------+>|/             |-|----+
    | +--------------+ |              | +--------------+ |    |
    | +--------------+ |period. update| +--------------+ |    |
    | |2.3 docs      |-+--------------+>|/2.3          |-|----+
    | +--------------+ |              | +--------------+ |    |
    | +--------------+ |              | +--------------+ |    |
    | |2.2 docs      |-+--------------+>|/2.3          |-|----+
    | +--------------+ |              | +--------------+ |    |
 +->| +--------------+ |              |                  |    |
 |  | |...           | |              |                  |----+
 |  | +--------------+ |              |                  |    |
 |  +------------------+              +------------------+    |
 |                                                            |
 |                                                            |
 |         +---------------+                                  |
 |         |WEB APPLICATION|                +-------------+   |
 |         |               |  redirect to   | unique edit |   |
 |         | - edit        |<---------------|    link     |<--+
 +-------->| - comment     |                +-------------+
 update &  | - approve     |   ,---.
  commit   | - report      |  /     \
           |               | / local \
           |               |( tempor. )
           +---------------+ \ repos /
                              \     /
                               `---'

The center of the new architecture is SVN. SVN contains all Forrest repositores. For the first, these are[1]:

These repositores are periodicially published using some kind of automatism (cron, forrestbot)

Let's look at the structure of the website:

http://cocoon.apache.org ................... contains the global docs
http://cocoon.apache.org/2.2/............... contains the periodically (e.g. every 6 hours)
                                             published docs

The "living docs" docs that are periodically published out of the current repositories contain an "edit" and a "comment" link. This link is redirected to a web application where authors can write new docs or comments, e.g.

http://cocoon.apache.org/edit/2.2/23.html --> http://someapacheserver.apache.org/webedit/edit/cocoon/2.2/23.html

http://cocoon.apache.org/comment/2.2/23.html --> http://someapacheserver.apache.org/webedit/comment/cocoon/2.2/23.html

The web application at http://someapacheserver.apache.org/webedit/ has following features:

The implementation of this mini CMS could be done based on

Document format

I propose the format that the default configuration of the HTMLCleaningConvertor generates. What is good enough for Daisy should work as well for us ;-) Alternativly we can use plain HTML4. This would have the advantage that the document can be edited using any HTML editor.

In the repository, each document consists of a directory, which can contain following files:

 ./content_en.xml ........................ content as cleaned XML
 ./content_en.html ....................... the content as HTML (only content_en.xml OR content_en.html are allowed)
 ./content_de.xml ........................ content in German
 ./meta.xml .............................. contains meta information (date, authors, status, target audience, keywords)
 ./comments_en.xml ....................... contains user comments in English
 ./comments_de.xml ....................... contains the user ccomments on the German version
 ./files/ ................................ contains all images and attachements

Note: Having the language postfix gives the chance to provide translations. For the first we concentrate on English documents.


Document identifiers

Forrest repositories

See http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/ for two examples that work with the latest SVN version of Forrest 0.6.

Published docs

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

What do we have to do?

Step by Step

The good news is that we don't need all the features at once. We can go the path to better docs and a better documentation system step by step:

CocoonDocumentationSystemSUMMARY (last edited 2009-09-20 23:40:41 by localhost)