cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Linden H van der (MI)" <>
Subject RE: Planet Cocoon license and reuse of docs
Date Wed, 25 May 2005 09:40:31 GMT

with all due respect for the various efforts to improve the
documentation, there is only one way to improvement and that is
screening all the available documentation on validity and clarity and
rewrite/enhance it when it's lacking or write the missing pieces. This
screening process is something that HAS to be done by hand, there is
nothing to automate about. 
If you want people to participate in this tedious but very important job
the only tools you need is some kind of repository for the "new"
documentation, a (team of) editor(s) that supervise the work and decide
on the quality of the content and the organisation of it and, most of
all, EASY and QUICK access to an editor that produces the documentation
in an acceptable form.

Don't bother writing YANDT (Yet Another Nifty Documentation Tool) but
look at what's available and use THAT. If all the time spent on writing
posts here ABOUT the documentation had instead been spent on WRITING
documentation, we would have had the best documented project on the

I look at all this from a documentation writer's point of view and I
repeat what I've said before: give me easy tools that produce documents
in a format that can easily be transformed into anything you guys dream
up to be handy, but most of all don't take ages to setup/startup and
don't need a 50-page user manual.

For now the only thing I've found that meets MY criteria is Daisy and
since Steven has already granted me some workspace I've started there.
True, this will not be the ultimate destination and yes, it might have
some drawbacks, but it works!

Let me propose an entirely different strategy:

- pick a tool, any tool that meets the criteria I mentioned above and
start a new set of documentation there. I suggest Daisy.

- everyone who wants to write documentation should use THAT tool, that
repository to write his or her document. Let's call this person a
writer. Before doing the actual writing we ask the writer to verify if
there is nothing on his topic in either wiki or 'official
documentation'. If there is, the writer should use the information there
and add it to the document.

- there are several committers that are also concerned about the
documentation and make themselves heard in every thread about the topic.
You guys know the code best and each probably has his own field of
What I would suggest is that you volunteer to be editor/reviewer in your
field of expertise. Your task in the documentation project will be to
review. So, the document written by a 'writer' is reviewed to see if the
document is valid (i.e. the information is correct and current). If you
feel something is missing you can either add it yourself of mark it for
the original writer to add (based on time constraints). When both of you
agree on the document it goes 'public', i.e. visible/usable for the rest
of the community.

When a document goes public and it includes information from the wiki
and/or the 'official documentation' the editor replaces those pages with
a link to the new document.

I know in an open source community there are not much 'rules' to be
enforced, but if you can set up rules for committing code, you might as
well set up rules for committing documentation. 

just my 2 ct.

Bye, Helma

> -----Original Message-----
> From: Ross Gardler [] 
> Sent: Wednesday, 25 May, 2005 01:11
> To:
> Subject: Re: Planet Cocoon license and reuse of docs
> Upayavira wrote:
> > Antonio Gallardo wrote:
> ...
> >> With the new apache zones, I think there is posible in a rasonable 
> >> amount of time (hours?) to setup a CMS to do the job.
> >>
> >> WDYT?
> > 
> > 
> > Then someone should do it, and we will see where that takes us. I'll
> > volunteer for the part of doing any document conversions 
> that might be 
> > required.
> I intend to do some experimentation over at Forrest with Daisy as the 
> CMS once we have Forrest 0.7 released (very soon now).
> In the meantime, I will continue to work with PlanetCocoon and other 
> such initiatives (the Wiki for exmample) to allow any content they 
> create to be incorporated into the Cocoon docs, and to provide a link 
> back to the relevant "host" CMS.
> When we have a working demo the Cocoon community can decide 
> if they want 
> to use it.
> Ross

View raw message