cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andy Lewis" <...@ascii27.net>
Subject Re: Documentation Format...
Date Fri, 15 Nov 2002 19:00:18 GMT

<snip/>
>
> +1.  The code is organized logically into packages, why shouldn't the  docs? :)
>

good point...mirroring the package structure would simply finding things....

>
> The current docs are "organized", in a sense, in that stuff that goes  together is sort
of
> globbed together, but I think the project would  benefit from something more logically
> organized.

agreed...

>
> If I go to x.a.o/cocoon looking for help in getting Cocoon speaking to a  database, do
I look
> in How-To's, Tutorials, or FAQs?  Or in the
> user-guide?
>

exactly the problem I've been running into...

>
> I've been of the opinion that PHP has the best documentation around, and  that we should
use
> them as a model for how to do things. Looking at the  PHP documentation, you'll see that
> there's more to "documentation" than  just "how to do things".  There's a quick reference
page,
> as well as a  "manual".  If PHP came in a box, that's what would be printed and  included
with
> it.  I hate to say it, but if the current Cocoon
> documentation was converted to print and then thown in the box, the  first thing I'd
do would
> be throw it out :)    All kidding aside, I  think we should try to make our docs as
> professional as possible.  Good  docs make or break a project.
>

Exactly! PHP has done an excellent job here. You would think with all this XML stuff around
we
could match it at least ;)
>
> Tony


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



Mime
View raw message