I am fine with either approach, but the OO doc (option 1) sounds like it's the most suited for our user/install/upgrade guides. The only 2 things that I would care about for the documentation are ...
1. that the proper docs are packaged in each release. 2. that all the docs are available via the web. the wiki solution is nice for #2, but sucks for #1. the OO doc is great for #1 and still works pretty well for #2, so I vote for the OO doc. Can we also make sure that if we are doing the OO doc that we also move the install and upgrade guides to the same format. -- Allen On Thu, 2006-01-05 at 10:35, 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 > > > > >
