Re: [Springframework-developer] Dcoumentation

[Colin S. <col...@ex...>]

That's pretty cool!   Aside from the question of generating 
HTML/PDF/whatever for individual docs, there is the question of the best 
mechanism to produce the web site.

One approach is obviously the Maven or Forrest one, where it puts out a 
site in a consistent format. This is pretty easy to use obviously. On 
the other hand, what I _really_ appreciate about the coWiki approach 
used by Hibernate to run their site is that it  encourages end-users to 
document their own tips and tricks, and makes it much easier for 
_anybody_ to add spontaneous documentation, which can possibly later be 
incorporated into the real docs.

So if Maven/Forest is used to produce the site, I think there should 
still be a friendly/usable wiki (like coWiki, as opposed to most Wikis, 
which scare people off), for supplemental documentation. Alternately, 
coWiki could be used for the entire site, the disadvantage there that 
it's pretty much harder to put it together as part of the build.

Regards,
Colin

Alef Arendsen (JTeam) wrote:

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