cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bertrand Delacretaz <>
Subject Do we need to scrap the existing docs and start over?
Date Thu, 03 Apr 2003 06:46:26 GMT
(Read on - it's not as bad as it seems ;-)

Reading Tony Collen's weblog at reinforces my thinking 
that the current organization does not allow the kind of disruptive 
work that is needed to make the docs happen.

The recurrent scenario in the last months is that someone brings a new 
idea, the discussion quickly centers around tools instead of content 
and after a few days everyone goes back in a wait state as there is no 
100% consensus on how to do things. I've been guilty too, I'm not 
pointing fingers here but I think this is a reality.

IMHO the main problems are

1) We're afraid of breaking the existing docs or offending their 
authors by making big changes to the navigation/layout/content/whatever
2) There is no sandbox where to safely experiment in small steps. The 
wiki is good for experimental content but not to work on the 
navigation/structure/presentation of the Cocoon web site.

But small steps and concrete results (=documents, navigation, layout, 
search features) are needed to converge the excellent ideas that have 
been exchanged here in the last few months.

I think it is critical that we allow people to work in small increments 
on this move: most probably several of us, like me, can commit small 
amounts of time to this here and there, but not the two-weeks full-time 
that would be needed for the big reworking that is (IMHO) needed.

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?

View raw message