cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject Re: Do we need to scrap the existing docs and start over?
Date Thu, 03 Apr 2003 14:33:21 GMT

On Thursday, April 3, 2003, at 01:46  AM, Bertrand Delacretaz wrote:

> Here's what I suggest:
> -create a new-docs subdirectory in the  (cocoon-2.1 or cocoon-docs) CVS
> -configure an alternate Forrest-based docs build using this as input
> -use this a a scratchpad to create a new web site with better 
> navigation and more consistent content, starting from scratch
> -gradually bring over the best existing CVS and wiki docs
> -switch the web site to new-docs once they are good enough
> How does this sound?

Sorry, it still feels top-down and it overlooks our richest, biggest 
resource -- users who contribute via wiki. The best thing that has 
happened to docs over the past year is wiki. What you are proposing 
above, unless it remains easily editable/note-able/accessible by our 
community via wiki or some other mechanism, is going to grow stale down 
the road. Just because it may be better than what we have now, it will 
remain incomplete (I still see no dedicated team of authors among us to 
fill in the current gaps), and after a while it will grow out of date 
again -- if users can't easily update it.

Furthermore, look at our content. A good chunk of it is about the 
project, having nothing to do with learning/using cocoon. Most of the 
rest is reference material with concept docs. We have a handful of 
tutorials, how-tos, and faqs.

Given our limited committer resources, here's how I'd approach this.

- separate out all docs relating to project administration, licensing, 
etc. Keep a single instance of these somewhere. Maintain these in xdocs. 
Refine/edit/refactor as approach

- Refactor our reference docs to be produced by some kind of 
auto-generation mechanism, as discussed and partially prototyped earlier 
(by Bertrand, Andy, Berni, and others) on this list. Much of the 
existing reference docs content can be used for this. Sometimes I think 
reference docs are the strongest domain of an open source project, what 
it can and should do very well. I'm honestly not sure about other doc 
types, whether an open source software projects can produce decent user 
docs like how-tos and user manuals without a dedicated team of authors, 
not doc tool builders.

- Leave all the rest -- How-Tos, FAQs, Tutorials, Concepts -- to a more 
open content system (via wiki/PHP-notes-like/simple CMS, etc.). Note, I 
fully expect committers to contribute to wiki, as they already are. This 
can develop into a full blown CMS down the road. For the moment, I see a 
wiki-docs generation handled elegantly by Forrest, with a few new 
features perhaps.

- If and when a committed group of authors appear, group write a better 
user manual. Or start one on wiki with a lot of guidelines/templates. 
However, I see this as a low priority for this, given the excellent 
books we already have.

Given our resources, given our users, I fail to see why we should 
perpetuate the closed-cvs-xdoc-editing system like the above. It doesn't 
produce timely content. We've had it for a long time. Simply rearranging 
content -- weeding out bad, even bringing in new stuff from wiki, adding 
tabs, changing navigation -- is like rearranging the deck chairs on the 
sinking Titanic. Please note that I'm NOT talking about Forrest, just 
about a cvs-based editing system. Cocoon is a vibrant, dynamic, 
innovative software project. I just don't think a cvs-based doc system, 
maintained primarily by committers and a few committed users, will ever 
be able to keep up with Cocoon's evolution, articulate useful 
information about the rich variety of problems Cocoon can solve, without 
the help of our wide user base.


View raw message