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