cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Glen Ezkovich <g...@hard-bop.com>
Subject Re: Planet Cocoon license and reuse of docs
Date Wed, 25 May 2005 13:20:00 GMT
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


Mime
View raw message