Hi everyone,
As someone who has written a fair amount of both code and
documentation I would just like to make a few comments. First, I
applaud your effort to manage Cocoon's documentation with a Cocoon
based CMS. I'm sure the Lenya and Daisy proponents will chime in
shortly with offers of support (soon to be followed by intense
bidding to be THE Cocoon CMS ;o)).
Second, don't expect a CMS to improve the state of Cocoon's
documentation. While a CMS is adept at managing work flows and
changes to a document, it is a poor excuse for a word processor or
even a simple text editor. The one thing I have learned over the
years is that using the correct tool for the job makes the job
several orders magnitude easier then trying to use one that can do
the job but was not designed for it. This is true in auto mechanics,
programming and documentation writing. Apple's Mail.app provides a
far superior editing experience then any online editor I have used.
(So does Outlook Express.) Yet, it pales in comparison to a an
application such as Bare Bones' TextWrangler, which in turn pales in
comparison to MS Word (in some respects). When I write an article or
a tutorial I write it in Word and copy my code from Idea. If this
then needs to be converted to html, I'll start working with
DreamWeaver (or better yet have someone else do it). When its needed
in XML it is a serious pain. It is usually easier to write a script
or program that does the conversion then do it by hand.
Third, Cocoon's documentation is not as bad as people think. I was
able to put together a fairly complex e-commerce site that included
custom generators and transformers, made heavy use of flow, used
third party web services and used several different types of
matchers among other sitemap tricks all from the documentation
available. Unfortunately I had to look long and hard to find what I
needed, but all I needed was there.
Fourth, documentation just like code needs to be reviewed and tested.
Someone other then the author needs to go through the tutorial or
article checking for facts, correctness and understandably.
Unfortunately, there are no unit tests for documentation. Along these
same lines there should be consistency in style and conventions. A
code snippet in one document should be formated the same as in any
other document. The whole of the documentation needs to be organized
in a coherent manner so that a user can find what they are looking
for quickly and easily. If a new user is looking for tutorials they
should be able to find them at a glance. Likewise if a user is
looking for information on CForms they should be able to find all
relevant tutorials and articles. A site search shouldn't be necessary.
If you want to improve Cocoon's documentation you need to accept it
in various formats and have someone convert it to what it needs to be
after appropriate vetting and editing. Forcing an editor or format on
authors will only deter them from submitting their work. CMSs and
other automated systems are wonderful at making things easier to
manage but not easier to create. Neither can they provide nor improve
content. That can only be done by people actually writing, editing
and maintaining the documentation. They are more likely to do so if
allowed to choose their own tools.
Glen Ezkovich
HardBop Consulting
glen at hard-bop.com
A Proverb for Paranoids:
"If they can get you asking the wrong questions, they don't have to
worry about answers."
- Thomas Pynchon Gravity's Rainbow
