On 12/17/05, Anil Gangolli <[EMAIL PROTECTED]> wrote: > > Nice doc! > > I think it's a step in the right direction to revision control docs with > sources and versioning will be easier than before, but I think we'll > still have some problems with this because the stored forms are > basically binary blobs. > > I'd like to push gently in the direction of using a source form that is > fundamentally text-based (XML, HTML or a wiki-based markup) and do all > of the guides (user, installation, admin and configuration) in a > uniform format. This will allow incremental contributions from more > than one source, contributions from readers as patches, merging across > branches, and understanding what's changed (or what wasn't updated) in > the docs from release to release. > > Looking at the Hibernate docs (which I like) they appear to use > Docbook and Apache FOP to get multi-page HTML, single-page HTML, and > PDF from one source xml, but, to be honest, I don't have any experience > with the formats and tools personally. Perhaps this is too long-term > and ambitious a goal, but this is where I think we should be headed for > documentation, at least in terms of general approach.
Spring and Hibernate use DocBook. I agree that having a text-based format for documentation is important. I've had great success with JSPWiki and documentation for AppFuse - but that's only because so many people have participated. The tutorials alone (50 pages printed) have been translated to 5 languages! I don't think this type of cooperation could've happened with documentation stored in Subversion - but I could be wrong. Matt > > --a. > > > > > Dave Johnson wrote: > > > Updating the user guide via the wiki has always been a pain, plus > > we've always wanted to ship a copy of the user guide with the release > > and I've always wanted a nice paginated and printable user guide... so > > this time I did the user guide in Open Office. I put the OpenOffice > > sxi file and the exported a PDF, they're here for your review: > > > > http://people.apache.org/~snoopdave/roller-user-guide-210.sxw > > http://people.apache.org/~snoopdave/roller-user-guide-210.pdf > > > > Comments and corrections are more than welcome. > > > > - Dave > > > > > > >
