On Fri, 2006-01-06 at 07:15, Anil Gangolli wrote: > 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.
I don't see why an OO doc wouldn't work here. Can't we have an OO doc managed inside the src tree and included in each release, then once a release is ready we export it to html and dump it on the website? Maybe we would even manage the doc as an 00 doc in the src tree, but export it to html to put on the website and export to txt to include in the release bundles. I am fine with managing in any format (txt, html, 00 doc), but I think that moving forward we should include the doc in each release and we should be able to export it to the website. Whatever format makes that easiest is fine with me. A potential 4th format alternative could be XML, which is somewhat harder to edit, but can be diffed and easily exported to various formats at build time. -- Allen > > 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 > > > > > > > > > > > > >
