cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bertrand Delacretaz <bdelacre...@codeconsult.ch>
Subject Re: Documentation Format...
Date Thu, 21 Nov 2002 09:16:59 GMT
On Thursday 21 November 2002 10:05, David Crossley wrote:
>. . .
> I do not agree with this. I think that we need certain information
> required as javadoc tags in the code before we can create *any*
> manpages, be they *-user or *-dev pages.

Is there an easy way to enforce the presence of these javadoc tags in the 
code?

> The table that is at the top of example Wiki:FileGeneratorManPage
> would be extracted directly from the javadoc tags, and would be
> needed for both sets of manpages.

Yes, sounds good, this is definitely info that can be provided by developers. 

> It is important to get that information and also the
> developer manpages done first, because they will form
> the basis for the user manpages. The former should be
> done by cocoon-dev and the latter can then be subsequently
> done by anyone.

Do we agree on what "user" and "developer" manpages are?

For me:
"user" is targeted at people using a component without modifying its java code

"developer" would be targeted at people working on the component's code. 

And I think in this view "user" pages are much more urgent, many exist 
already but would benefit from being refactored into a well-structured set of 
manpages. 

I don't think developers have been complaining about lack of docs (the code 
is well structured and well written), but *users* are complaining often.

-Bertrand

Mime
View raw message