Mike Edwards wrote: > I really would like to make a distinction here between source form > documents and final form documents. > > I agree that anything placed on the website as a final form document > should be in a generally acceptable "open" form. HTML, Maven Xdoc, > PDF, for example. Word documents are NOT acceptable as final form. >
I agree. I think the biggest thing that determines final form should be how people will read these documents: html is good for online use, pdf is good for offline/printing. It may be appropriate to publish the same information in different forms if people use it differently. > Source form documents are a different issue in my opinion. These should > be in a form that permits straightforward editing. For longer > documents, formats like Word or OpenOffice seem reasonable, since you > need the capability of good editing software to handle these documents. > I don't think that formats like these should be outlawed for source form. > I think we need to be careful about the accessibility of these formats to authors. As an author you want an easy editing experience; however, you also want other people in the community to be able to assist with/contribute to that editing process. An important factor here is how high the barrier to entry is for other people in the community who wish to join in this editing process. For example, MS-Word is prevalent in the Western commercial world; in other parts of the world it may not be so accessible. Think also about how other people can contribute modifications to the source documents. It is easy to review a patch to a simple text file but very hard to do for a binary document or one generated from some tool. > I don't regard Maven xdoc as a good source form for longer documents > since there is no tooling that I have discovered that helps edit them > other than a simple text editor. DITA requires tooling to help - and my > contacts in the IBM ID department indicate that DITA tools are complex > and require education. > > HTML is OK-ish as a source form. There are at least some good open > source tools to help edit it. Plain text simply doesn't look good for > longer documents - and loses useful capabilities like hyperlinks. > When you look around other Apache projects you see a variety of formats used but most come down to fairly simple text-based files. Developers here tend to be lazy^H^H^H take path of least resistance when it comes to documentation. That they tend to stick with hard to edit but open forms says something; in the end having someone else help keep the document up to date is easier than doing it all yourself :-) -- Jeremy
