cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andy Lewis" <...@ascii27.net>
Subject Documentation Format...
Date Thu, 14 Nov 2002 16:23:45 GMT

I've just recently joined the documentation list, 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. 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 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.
Comments?

Thanks!
Andy Lewis

-- 
"The heights of genius are only measurable by the depths of stupidity."



Mime
View raw message