Sean Landis wrote:
Marc Portier <mpo <at> outerthought.org> writes:
Some of my TOC additions embedded, feel free to comment...
(incorporated the suggestions from issue 21 and those made in this
thread already)
I also added a big section on doing reslet based development as I think
there is a big difference in listing 'what it is and does' versus 'how
one should combine things to solve typical problems'
other suggestions?
regards,
-marc=
[...deleted...]
I was just about to follow up on the original TOC saying that it looked too much
like a reference manual. I think you are right on, Marc, in suggesting to
include a beefy amount of 'how to'. My personal preference for Java projects
is to only focus on how to and let the JavaDoc worry about "what it is." but
maybe that's too extreme. I'm thinking about the DRY principle here.
Sean,
I do think your statement is a bit extreme: IMHO there _is_ room for a
more textual and literate explanation of what the API is about next to
what the typical javadoc contains.
The latter is often targetted towards technical details, extension
points and pure public interface documentation, while the former could
be stressing on 'principles', 'motivations', and 'broader
collaborations' and more easily contain UML like diagrams to help get
the picture through.
As mentioned earlier we can introduce a "javadoc:" linking convention in
Daisy that should provide a way to avoid the 'repeating ourselves' by
inserting direct pointers to the apidocs.
More interestingly though:
Anyone having more input for the suggested howto section?
I know I've kept things rather unspecific atm, more detail in that part
of the toc might help growing a feeling of need and usefulness?
wdyt?
regards,
-marc=
