On 1/5/06, David M Johnson <[EMAIL PROTECTED]> 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.
