cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject Re: Documentation Format...
Date Sat, 16 Nov 2002 12:20:01 GMT

On Thursday, November 14, 2002, at 11:23  AM, Andy Lewis wrote:

> I've just recently joined the documentation list,

Welcome! Thanks for joining.

> and wanted to through out a couple of ideas.
> First off, I have been using Cocoon since 1.3, and am currently 
> developing a portal solution for
> NASA using 2.1-dev.

I remember hearing about it. I also remember Stefano asking if you could 
write up some kind of a doc (e.g. success story?) about it. Was that 
ever possible, given your client?

> Part of that effort includes bringing other people her eup to speed on 
> the
> technology. I have to say that ,while the Cocoon documentation has ben 
> improving steadily, it is
> still a huge struggle to even point someone to the correct place.

I think almost everyone would agree with you. I also remember an earlier 
post from you on cocoon-dev saying that "books are your friends". 
Speaking **only** for myself, not the Cocoon project, I deliberately 
chose not to reorganize the docs when I started working on the docs 
(about six months ago). Several books were about to be released. I think 
books are worth their "weight in gold". I knew, as one person with 
limited time, that I could never do anything that would be as good. I 
decided to use my limited committer/volunteer time to increase the pool 
of authors. So I wrote up a bunch of guidelines to facilitate this and 
have done a lot of "handholding" of new authors as they come forward. I 
think we've all been waiting to do anything from a reorganizational 
perspective until the Forrest transition occurs which may happen very 
soon. If you have ever compared Cocoon's doc generation framework to 
Forrest's, you'll understand why.

> I am not making these comments without suggesstions however, as my 
> intent is to be constructive
> here so please pardon any presumptiousness on my part. Cocoon is, as we 
> know, extremely modular,
> and becoming increasingly so. But documentation seems to be ither 
> sparse, or scattered. I recall
> the threads about how to organize it, and have seen some efforts down 
> that path. But the first
> thing that comes to mind is that if I want to know the details ofa 
> particular input module or
> transformer, I can't find it in a a single place. There is some 
> reference material, and some
> concept material, and some tutorial material, each introducing new 
> technical information. Also I
> have seen that, as the code evolves, docs get left behind. I would gues 
> that part of this is
> because there are multiple places to update. This brings me (at long 
> last) to my suggestion. What
> about a UNIX man page approach to technical docs? For each transformer, 
> gerneator, inputmodule,
> etc, have a sinlge man page type document with the technical details, 
> samples if any, formats,
> etc. This would help developers and users both have a single stop for 
> such info. Of course this is
> only one aspect of documentation. The project still needs concept 
> documents, JavaDocs, tutorials,
> etc. But as a basic level for technical information users need, I think 
> it would make a
> substantial difference.

I think some kind of granular approach to reorganizing docs would help. 
That way, one could organize/present them to users the in many different 
ways, not simply by user type, packages, etc. Many share your belief. 
What we need is some kind of proposal or proof of concept, if someone 
*really* wants to do this.


View raw message