cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Linden H van der (MI)" <H.vanderLin...@MI.unimaas.nl>
Subject RE: Planet Cocoon license and reuse of docs
Date Wed, 25 May 2005 13:30:19 GMT
> > - 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.

In short a CMS type of tool

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

Since documentation is best gathered in a CMS, because there will likely
(hopefully) be more than one person working on it, this inevitably means
that everyone should use THAT CMS to avoid scattering documentation all
over the place (wiki, website, mailing list, blogs, own websites etc).

> What if the new document is far superior to the existing in terms of  

Hurray for that. But if you've come up with something that replaces
information in other places, do note that in both "origin" and
"destination" to avoid others duplicating the effort.

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

Great! Go ahead. If you feel comfortable enough to write something about
any aspect of Cocoon, please do. The only thing I ask from reviewers
(aka Cocoon committers) is that they read your document and compare what
you write to the actual working of Cocoon to see if there are
discrepancies that might lead to false conclusions/understanding from
other users.

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

OTOH If you write down that CForms has a state 'readonly' when in fact
it's 'disabled' that's something Sylvain e.g. will probably notice
immediately while it takes trial and error of 'ordinary' users to figure
out.

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

True, but even the multiple attempts to come up with a general TOC have
failed so what now? Putting all documentation in one place (at least the
'user guide' type which is most needed anyway), following a general
structure/TOC is still better than the current state.

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

Ok. Let's sit down then and dream up a general TOC by studying the
attempts done earlier.

Bye, Helma

Mime
View raw message