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 09:05:43 GMT
Andy Lewis wrote:
> Bertrand Delacretaz wrote:
> >Andy Lewis wrote:
> >>. . .my intent with the man pages was user-level technical
> >>documentation...
> >
> > same here, but hearing other comments makes me think that we
> > might need TWO  reference pages
> > (manpages) for some components, one for users (who use the
> > components) and one for developers
> > (who might want to modify or inherit them).
> 
> intersting...hm....what would go in the developer man page that
> wouldn't fit in the javadocs?
> 
> >
> > We might want to leave this open by first creating manpages named
> >
> > 	xxx-user-manpage.xml
> >
> > and leave
> >
> > 	xxx-dev-manpage.xml
> >
> > available for future use.
> >
> > -Bertrand

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.

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.

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.

Another important reason is that we need to get some
system in place soon to ensure that developers do not
continue to write code that has insufficient accompanying
documentation.

--David




Mime
View raw message