[Cocoon Wiki] New: CocoonDocumentationSystem

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

   Date: 2005-01-13T22:53:11
   Editor: ReinhardPoetz
   Wiki: Cocoon Wiki
   Page: CocoonDocumentationSystem
   URL: http://wiki.apache.org/cocoon/CocoonDocumentationSystem

   no comment

New Page:

= Motivation (or problems I want to solve) =
 * make writing docs as simple as possible
 * separation between global docs (docs about the project) and user docs
 * evaluate the existing docs (no automatic doc import into new repositories)
 * enable comments for docs
 * have a modular architecture (having a repository and webspace should me enough to run, other features should be "plugable")

= Architecture =

== Overview ==
{{{
    +------------------+              +------------------+
    |SVN REPOSITORY    |              |  COCOON WEBSITE  |
    | +--------------+ |period. update| +--------------+ |
    | |global docs   |-+--------------+>|/             |-|----+
    | +--------------+ |              | +--------------+ |    |
    | +--------------+ |period. update| +--------------+ |    |
    | |2.3 docs      |-+--------------+>|/2.3          |-|----+
    | +--------------+ |              | +--------------+ |    |
    | +--------------+ | (frozen)     | +--------------+ |    |
    | |2.2 docs      |++--------------+>|/2.2.2        | |    |
    | +--------------+ |'-._          | +--------------+ |    |
 +->| +--------------+ |    `-..      | +--------------+ |    |
 |  | |...           | |  (per. `-----+>|/2.2          |-|----+
 |  | +--------------+ |   update)    | +--------------+ |    |
 |  +------------------+              +------------------+    |
 |                                                            |
 |                                                            |
 |         +---------------+                                  |
 |         |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]:

 * 2.1 docs
 * 2.2 docs
 * global docs

There are two ways how the docs of these repositores are published:

 * periodicially using some kind of automatism (cron, forrestbot)
 * when a new Cocoon version is released, the docs are released too

Let's look at the structure of the website:
{{{
http://cocoon.apache.org ................... contains the global docs
http://cocoon.apache.org/2.2.0/............. contains the docs that were (will be) published
                                             when Cocoon 2.2.0 was released
                                             *** These docs will ever never change! ***
http://cocoon.apache.org/2.3.4/............. same as above but for the 2.3.4 release
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:

 * edit a document e.g. document 2.2/23.html (everybody)
 * save the modified document in a local repository (everybody)
 * commit the document to SVN (committers only)
 * get a list of all locally available versions and the latest SVN version
   of a document so that the author can select from which version he wants to start
   (everybody)
 * add a comment to a document (everybody)
 * commit the comment to SVN (committers only)
 * send mails to docs@cocoon.apache.org when a new doc or comment has been written
 * make site.xml editable using a nested list of <ul> (committers only)
 * user management (committers only)
 * report: list of all modified/new docs and comments available
 
[1] If 2.2 is coming soon we should concentrate on 2.2 docs 

== 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 contains of 3 files:
{{{
 17.xml ........................ contains the content
 17.meta.xml ................... contains meta information (date, authors, history)
 17.comments.xml ............... contains user comments
}}}
Splitting up the docs into three parts has the advantage that the structure of each document is simpler, editors can be used to edit the content only. Also Openoffice goes this way.


== Document identifiers ==
I think we should move away from speaking names like "custom_components" and use plain numbers and put all documents into a flat directory. Speaking identifiers are nearly always a problem in data modelling.

Advantages:
 * no misleading document names
 * several navigations can be provided
 * during the life of a document, a speaking identifier may become out of date

Note to auto-generated docs: Every process that generates docs automatically, has to use a numbering scheme (namespace) so that IDs can't conflict with existing docs.

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

== Published docs ==
The proposal for new global docs and user docs are available at http://apache.org/~reinhard/cocoon/1.html. Note that the page is generated out of two forrest repositories.

The global repository is responsible for the tabs "Projekt" and "Community". The tabs "Getting started" and "Documentation" link to the most recent, editable userdocs. Older (frozen) docs get their links in the second-level pelt in the "Documentation" tab.

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

 * Step1: Setup Forrest Repositories
   * work on the new docs
   * evaluate good docs and move them into the new repository
   * find a new structure
   * integrate auto-generated docs
 * Step2: enable the periodically running jobs that publish repositories
 * Step3: work on the web application

== Who does the work? ==

 * work on the new docs (writing new ones, update existing ones) (Upayavira)
 * setup the new Forrest repositories (ReinhardPoetz)
 * initial '''proposal''' for a new structure (ReinhardPoetz)
 * enable publishing process (n.n.)
 * write the web application (ReinhardPoetz)
   * component that reads from and committs to SVN (n.n.)
   * do the SSL setup of Apache (n.n.)

== Roadmap ==
 * I will work on the new Forrest repository and the proposal for the new structure in January. (ReinhardPoetz)
 * In February I want to provide a first prototyp for the web application running on brutus.apache.org (ReinhardPoetz)
 * In March we should find a home for the web application. AFAIK applications running on brutus.apache.org (the Gump machine) are not allowed to committ into our sVN (ReinhardPoetz)
 * Upayavira will invest a large amount of his time into writing and updating docs.