Latex? :-) I'm fine with whatever Dave prefers though.
Elias On 1/6/06, Allen Gilliland <[EMAIL PROTECTED]> wrote: > 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 > > > > > > > > > > > > > > > > > > > > > >
