cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@indexgeo.com.au>
Subject Re: Documentation Format...
Date Thu, 21 Nov 2002 10:11:23 GMT
Bertrand Delacretaz wrote:
> 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?

I do not know. Let us make one, if there is not.

I am expecting that the reference doc generation system
that Berni proposed would be able to also summarise the
codebase and report any lack. It is amazing how quickly people
attend to things when they see their listed in a table of
"author" versus "gold stars", or a nag email to cocoon-dev,
or something simple.
 
> > 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?

Well spotted. This is very important to define up-front.

> 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 working on other components. I still do not understand how
my own code interacts with the rest of the wonderful Cocoon beast.

Your definition is a good start but not quite there.

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

Agreed.

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

I would complain if i was the type. I see serious lack
and inconsistency. Even the javadocs are not very good.

Rather i tried to encourage reference docs the last time
that Berni's proposal came up.

I jumped straight in to open source as a Cocoon developer,
intending to patch as i learned. The "Dive in and learn on
the job" method has worked well. However, i was seriously
confused at the beginning and still am. I need well-structured
reliable developer documentation, even if is just the
one line definition of the component and its usage table.

Actually, i am looking forward to these ensuing discussions
of each component and their parameters. Building the
documentation is where we will learn most.

--David


Mime
View raw message