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:16:00 GMT

On May 25, 2005, at 4:40 AM, Linden H van der (MI) wrote:

>
> Let me propose an entirely different strategy:
>
> - pick a tool, any tool that meets the criteria I mentioned above and
> start a new set of documentation there. I suggest Daisy.

What you should be concerned about is managing new and existing  
content. This includes some process for accepting vetting, editing/ 
correcting and publishing.

>
> - everyone who wants to write documentation should use THAT tool, that
> repository to write his or her document.

Why require a particular tool? Is everyone who contributes code to  
Cocoon required to use Eclipse?

> Let's call this person a
> writer. Before doing the actual writing we ask the writer to verify if
> there is nothing on his topic in either wiki or 'official
> documentation'. If there is, the writer should use the information  
> there
> and add it to the document.

What if the new document is far superior to the existing in terms of  
content and clarity? Who decides this? Do we leave this decision to  
the author? Frankly if I'm going to write some documentation, I'm  
going to do it because I'm unhappy with what exists and I am likely  
to start from scratch or just completely rewrite what exists.

>
> - there are several committers that are also concerned about the
> documentation and make themselves heard in every thread about the  
> topic.
> You guys know the code best and each probably has his own field of
> expertise.
> What I would suggest is that you volunteer to be editor/reviewer in  
> your
> field of expertise. Your task in the documentation project will be to
> review. So, the document written by a 'writer' is reviewed to see  
> if the
> document is valid (i.e. the information is correct and current). If  
> you
> feel something is missing you can either add it yourself of mark it  
> for
> the original writer to add (based on time constraints). When both  
> of you
> agree on the document it goes 'public', i.e. visible/usable for the  
> rest
> of the community.

This is an essential step in producing good documentation. It is also  
a very time consuming one. Experts are very useful when it comes to  
verifying the broad pictures and approaches but to often their  
knowledge of the field makes it easy for them to understand the  
intention of the author when a newbie will be completely lost.


>
> When a document goes public and it includes information from the wiki
> and/or the 'official documentation' the editor replaces those pages  
> with
> a link to the new document.

Unfortunately this leads to pretty much the same state we have now, a  
lose collection of documents some easy to locate and some buried  
deep. Someone needs to manage the documentation. Someone needs to  
organize it. While this can be a community effort ultimately  
decisions need to made as to where documentation is to be located and  
organized and this needs to be done in a consistent manner.

>
>
> I know in an open source community there are not much 'rules' to be
> enforced, but if you can set up rules for committing code, you  
> might as
> well set up rules for committing documentation.

The issues are different, but of course rules are needed. With code,  
test can be run to verify correctness. Bugs pop up as others work on  
different parts of the code. With documentation decisions need to  
made by people as to its value, its understandability and where it  
fits in the grand scheme of things. Someone needs to go through it  
and insert the appropriate hyperlinks. Random documents no matter how  
informative will not make Cocoon any easier. Its as much about  
organization and ease of use from a users point of view as it is  
about content and currency.

just my 1 1/2 cents



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