You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@roller.apache.org by David M Johnson <Da...@Sun.COM> on 2006/01/05 19:35:18 UTC
VOTE: which user guide format for 2.1?
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
Re: VOTE: which user guide format for 2.1?
Posted by Allen Gilliland <Al...@Sun.COM>.
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
>
>
>
>
>
Re: VOTE: which user guide format for 2.1?
Posted by Elias Torres <el...@torrez.us>.
Latex? :-)
I'm fine with whatever Dave prefers though.
Elias
On 1/6/06, Allen Gilliland <Al...@sun.com> 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
> > >
> > >
> > >
> > >
> > >
> > >
> >
>
>
Re: VOTE: which user guide format for 2.1?
Posted by Allen Gilliland <Al...@Sun.COM>.
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
> >
> >
> >
> >
> >
> >
>
Re: VOTE: which user guide format for 2.1?
Posted by Anil Gangolli <an...@busybuddha.org>.
I should note that the proposal does describe why denormalization was
chosen in this case, and it was at least a conscious decision.
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.
>
> 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
>>
>>
>>
>>
>>
>>
>
>
Re: VOTE: which user guide format for 2.1?
Posted by Anil Gangolli <an...@busybuddha.org>.
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
>
>
>
>
>
>
Re: VOTE: which user guide format for 2.1?
Posted by David M Johnson <Da...@Sun.COM>.
Ted,
I used Open Office's merge document feature to import your changes
and to review each one. I didn't realize OO had such a thing, but it
does and it seems to work pretty well. So we have merge/diff after all.
- Dave
On Jan 17, 2006, at 1:07 PM, Ted Husted wrote:
> I went through the Open Office version of the 2.1 User Guide and
> posted some patches here:
>
> * http://opensource2.atlassian.com/projects/roller/browse/ROL-996?
> page=all
>
> I notice that reports of new and and changed JIRA tickets are not
> being sent to the dev list. Typically, an ASF project is configured so
> that all the logs are sent to the dev@ or commit@, so that the PMC can
> follow all the changes being made to a project.
>
> -Ted.
Re: VOTE: which user guide format for 2.1?
Posted by David M Johnson <Da...@Sun.COM>.
Thanks Ted, I'll incorporate those changes ASAP.
- Dave
On Jan 17, 2006, at 1:07 PM, Ted Husted wrote:
> I went through the Open Office version of the 2.1 User Guide and
> posted some patches here:
>
> * http://opensource2.atlassian.com/projects/roller/browse/ROL-996?
> page=all
>
> I notice that reports of new and and changed JIRA tickets are not
> being sent to the dev list. Typically, an ASF project is configured so
> that all the logs are sent to the dev@ or commit@, so that the PMC can
> follow all the changes being made to a project.
>
> -Ted.
Re: VOTE: which user guide format for 2.1?
Posted by Ted Husted <te...@gmail.com>.
I went through the Open Office version of the 2.1 User Guide and
posted some patches here:
* http://opensource2.atlassian.com/projects/roller/browse/ROL-996?page=all
I notice that reports of new and and changed JIRA tickets are not
being sent to the dev list. Typically, an ASF project is configured so
that all the logs are sent to the dev@ or commit@, so that the PMC can
follow all the changes being made to a project.
-Ted.
Re: VOTE: which user guide format for 2.1?
Posted by Ted Husted <te...@gmail.com>.
On 1/5/06, David M Johnson <Da...@sun.com> wrote:
> 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.
The price paid is that it becomes extremely difficult for more than
one person to work on the documentation in an asynchronous way. It
also becomes very difficult for the PMC to provide oversight over the
documentation. When a change is made to the documentation, how will be
PMC be apprised?
If the PMC has no way of following changes to the documention and a
commit-by-commit basis, then we imply that that each member of the the
PMC have to re-read all the OO documentation, end to end, before each
and every release vote. If not, then a vote of the PMC boils down to
"we trust that someone else did the right thing", and it would not be
a true PMC. A true PMC is comprised of three or more individuals who
are each providing active and conscientious oversite for the entire
project.
I would suggest that using the OO format begs the question of how many
people can work on the documentation, as well as how many people are
able to provide oversight. Instead of being a scalable number, the
number becomes one.
One maintainer for the documentation may be the situation now, but
that would not be an ASF preference. A core ASF principle is that we
hold all the code and documentation in common. The single maintainer
mentality is one of the conditions that incubation is meant to cure.
I do agree that using OO would be more efficient for a maintainer. I'd
love to be able to use it with projects like Struts and iBATIS. But,
it is not more efficient if the documentation is going to maintained
by the community, rather than by one hardworking individual.
Of course, a third alternative would be to use an XML format and
render it with stylesheets. Tools popular with other ASF projects
include Forrest, Maven, or Anakia. I can't volunteer to help setting
up something like that in January, but I would be able to help in
February.
-Ted.