Document publishing worklow (was Re: Expert pre-defined/community post-defined?)

[Ross Gardler <rg...@apache.org>]

Stefano Mazzocchi wrote:

> I like the notion of
> 
>  daisy -> forrest -> out
> 
> makes very good sense.
> 
> Now we just need to find a way to automate a little that workflow, but 
> without introducing security vulnerabilities.

How about this (bullet summaries followed by textual description.

Daisy as editing environment.
	- anyone can edit
	- people are given quick "committership" here
	- change mails are sent out by Daisy for docs committer review
         - docs committers review changes and publish to the daisy repo

Forrest as publishing tool
         - cocoon committers manage a
	- brings together XDocs, wiki docs, Daisy docs etc.
	- publish to (or dynamically host on) a staging server

Offical Docs site
	- live Apache site is pulled from staging server

Daisy as editing environment
----------------------------

Daisy-Wiki provides WYSIWYN (What you see is what you *need*), wysiwyg 
editing, version control, user admin, semi-structured docs management, 
email notification of edits, comment system and much much more.

Since the Dasy repository is completely separate from the code base 
committership to this repository can be more freely given. The job of 
the docs committers (editors?) is to ensure that content is of a 
reasonable quality and is appropriate content (i.e. keep out spam).

It is *not* the job of these people to ensure technical accuracy of 
content, although it is hoped that they will do there best here too.

This gives us the first phase of our approval process:

	- any user edits docs in the Daisy Wiki
	- mail sent to either the docs list
	- edit is approved/rejected as appropriate
	- mail is sent out to docs list

When a new page is published to the Daisy wiki then a dev is tasked with 
reviewing that page for incusion in the docs content object (discussed 
further in the next section>

Forrest as publishing tool
--------------------------

A separate Forrest site is used to create the official docs for Cocoon. 
The structure of this site is managed by the devs and is maintained in 
SVN. Since it is the devs who manage this site structure they have final 
control over which of the Daisy published docs are considered good 
enough for the offcicial Cocoon stamp of approval. In other words, this 
is the point at which the technical accuracy of the docs is maintained.

The final Cocoon documentation can include content from many sources. 
For example there are the existing SVN docs, the wiki docs and other 
docs generated by other sites. Cocoon commiters manage a docs "content 
object" that bring together all these different sources and attached 
appropriate credits for third party docs that are given the official 
"Cocoon seal of approval".

It is worth noting that the Burrokeet (http://www.burrokeet.org ) 
project is developing a GUI interface for managing such content objects.

This content object is published to a staging server via SVN and thus 
devs are notified of docs changes automatically and a record of the 
"official" documentation is kept in SVN (some people felt this was a 
requriement).

This gives us the second phase of our approval process since devs are 
monitoring the SVN commit logs anyway.


Offical Docs site
-----------------

The official documentation is pulled from the staging repository using 
rsync or similar by a process triggered by the devs at an appropriate 
time and managed by a docs release process.

What needs to be done?
======================

The daisy wiki needs to be hosted somewhere.

The Daisy plugin for Forrest needs to be completed (I'm volunteering for 
this)

The last stage (syncing to the public site) needs to be fleshed out and 
a release process needs to be written to decide how and when this 
syncing is done.


????


Ross