For the user guide I'm ok with (1), primarily because there's usually
only one author anyway (Dave J), and he seems to prefer it.
I don't think the same strategy would work for the installation guide,
faqs, etc., and I don't hear that being proposed. This means the same
issues versioning in wiki space we have had (ok, Dave has had) for those.
For all of the other docs I favor something along the lines of ...
(3) HTML doc tree revision controlled along with sources, distributed
with releases. Contributions accepted from non-committers as patch
diffs. I think this is what the Tomcat project does for example. No
pdf. No wiki-based editing, but also none of the issues (e.g. random
losses of & due to browser textbox treatment) and limitations (e.g.
working with attachments) around editing.
or
(4) Other text-based markup format processed via the build. Again,
contributions accepted from non-committers as patch diffs. Possibility
of generating html single-page, multi-page, and pdf from one source.
Some sites (I think JBoss and MySQL projects tend to do this) also
combine static docs with public user comment sections that are
wiki-based. That might be worth looking at but I think requires more
development effort.
--a.
David M Johnson wrote:
Right now, we've got two easily within grasp choices for the Roller
2.1 user guide format. I don't want to decide alone which one to
use, so I'd like to call a vote. Here are the options:
*** 1) Use my new Open Office version of the user guide
I've written a reasonably complete Roller 2.1 user guide in Open
Office 1.X format.
Find it here: http://people.apache.org/~snoopdave/doc_drafts/
Should we use it for 2.1?
Advantages:
- Editing via a nice (open source!) word processor with spell
checking, PDF generation, nice drawing tool for diagrams, etc.
- Open Document Format is a truly open standard with support for XML
- Can can easily produce HTML and PDF versions of the doc for the
website
- History: the original Roller article was written in Open Office ;-)
Disadvantages:
- Not a text friendly easy to diff/merge format
*** 2) Continue to use a big wiki page for the user guide
Or should we stick with the UserGuide_2.x wiki approach?
Advantages:
- Easily editable (assuming that I grant you a user account on my
wiki ;-)
- Wiki does good diff, makes recent changes newsfeed available (very
handy)
- Wiki user guide fits in well with the Roller wiki, hyper-links,
wiki goodness, etc.
Disadvantages:
- Not distributed as a file in the Roller release and no PDF
- We've (OK, I've) had trouble managing different versions and
attachments
There are other options, but these are the ones we have ready now for
2.1. Actually, that's not entirely true, if we go with wiki, I'll
have to port my Open Office document back to wiki syntax (grumble
grumble).
So, with all that in mind, which one should we go with for 2.1?
I vote for #1
Here's why. We don't really have a documentation team hammering away
at different versions of the user guide for different release of
Roller, so I don't think diff/merge are that important. Plus, Open
Office may eventually have some form of change tracking suitable for
small teams. For me, losing diff/merge is a small price to pay for
the ease-of-use, diagram editing, printer-friendly and PDF generating
features of OpenOffice.
- Dave
