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 Tue, 19 Nov 2002 18:22:59 GMT

> Diana Shannon wrote:

<snip/>

>> In addition to generating a great set of reference docs, I assume we can pull snippets
from it
>> for use in many other docs, correct?
>
> Yes, great idea.

I hope so...

>
>> However, remember SoC. Do we really want people (potential doc
>> contributors) without a lot of Java experience tweaking source files to add this
reference
>> info?
>
> If they make an attempt to rectify some lack, and get it wrong,
> then the developers that are responsible for that particular code
> might leap into action.

yeah...but still...developer docs in the code, user docs outside the code.

>
> The tool that creates the reference documentation could generate
> a summary of all javadoc attributes that we could then run by
> the cocoon-dev list for quality control.
>

Again, what infor are we looking ot put into the javadocs? Shouldn't we try to figure out
what the
man pages should contain first, then figure out the best way to track and maintain each piece?
We
should be working backwards here from the end goal, not forwards from the tools we have.
> It will be committers who will apply the patches that are
> contributed, so at least one other person gets to review
> the work.

Which seems to create a documentation bottleneck actually. Do we really want to create a situation
where a developer needs to review technical documentaiton to make sure it does affect the
code?
>
> These changes and capability will be going into the head
> of CVS first, so i do not see any problem.
>
> --David

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



Mime
View raw message