[Springframework-developer] Dcoumentation

[Alef A. \(JTeam\) <al...@jt...>]

I've been spending some time on the documentation question (summary of
what's been discussed can be found below).

Basically when the KISS principle applies, the Hibernate approach is
pretty cool. Documentation defined in DocBook, transformation done using
DocBook XSL (found on SourceForge) to both PDF and HTML (singlepage and
multi-page)...

I've also had look at Forrest. To be able to run it, I needed to
checkout the sources from forrest and build it. The CVS was somehow
corrupt, so far for Forrest :)... No, without jokes: Forrest has this
concept of the generating a site and from there on, generate other
documentation. With some advanced configuration you can aggregate
multiple pages into a singel PDF file (but like I said, advanced
configuration, not really documented and stuff). Then there is the
problem that the default document format is XDoc and we'll have to tweak
forrest to get DocBook working (won't really be a big problem, but
still). Also, I don't really like to get stuck to Forrest for the site
as well!

Ok, like I said, I've took a look at the Hibernate approach and copied
some of our docs into the structure they have. Within half an hour I got
everything running... Results at
http://www2.jteam.nl/spring/index.html... It's just DocBook xml files,
generation takes about 30 seconds...

I'd like to transform all documentation we have (which is pretty much
including the tutorialpdf and stuff) to some sort of reference doc to
achieve consistency. I can transform some of the documentation we
already have, but still, it's probably a lot of work to get something
like the Hibernate referecne docuemntation ready...

What do you think???

Alef

Summary of discussion:

<colin>
As for docs, most people generating docs with maven are using the XDOC 
plugin. It works pretty well, but the XML dialect is not any sort of 
standard. In that respect, while doing DocBook (with Forrest, or 
whatever mechanism) is a bit more complicated, there will be more 
advantages later as tool support picks up.
</colin>

<darren>
I think docBook (or any other format that would allow generation of
multiple user formats) is a good idea.  Don't have any experience of
Forrest but it seems to have some good reviews and looks pretty simple
to pick up.
</darren>

<alef>
I was thinking about having somewhat more integrated docs like
Hibernate. Hibernate's using DocBook as the structure of their
documentation. I think that's quite good sice you can do anything with
it (generate pdf, html, etc). We've discussed Maven shortly, but my
opinion is that it's too much project oriented. Also, we don't really
need the build functionality Maven provides. Forrest sounds like another
option too... Does anyone have experience with it?
</alef>



==
JTeam B.V.
Donker Curtiusstraat 7-412
1051 JL  Amsterdam
T: +31 20 486 20 36
M: +31 6 24 11 1996
F: +31 84 837 00 00
E: al...@jt...
W: http://www.jbosssupport.nl
W: http://www.jteam.nl