Not everybody (hi Anil!) agrees that Open Document format is the
right format for the Installation Guide, but I decided to go out on a
limb and convert it from wiki to ODT -- a desperate measure to
convince the doubters that I am right.
I also updated the install guide content for 2.1 and rewrote much of
the document for better clarify and completeness.
Personally, I think the wiki is great for collaborative document
development -- things like proposals, FAQ files and up-to-the minute
docs such as release notes. But for formal documents like the user
guide and installation guide, I much prefer using a real word
processing system with a user-friendly interface and the ability to
save to PDF and HTML.
So take a look, the user and install docs are here in ODT and PDF
format:
http://people.apache.org/~snoopdave/doc_drafts/roller-install-
guide-210.odt
http://people.apache.org/~snoopdave/doc_drafts/roller-install-
guide-210.pdf
http://people.apache.org/~snoopdave/doc_drafts/roller-user-
guide-210.odt
http://people.apache.org/~snoopdave/doc_drafts/roller-user-
guide-210.pdf
Aren't those PDFs nice. And we've got bold text inside the roller.xml
file to indicate what needs change.
The advantages of using ODT instead of wiki for the install guide are:
- Nice paginated format suitable for printing
- Can be shipped in our distribution for off-line reading
- No more messing with file attachments on the wiki
- No more XML ampersand mixups
- Can be checked into the SVN repository
- Still retain ability to merge and diff documents
- Still retain ability to link back to the wiki
For release notes, which can be updated even after the software is
released, we should still use the wiki.
Doubters: what say you?
- Dave
