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.
Diana
