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