Kepler

Our current documentation system creates a lot of unnecessary work and has excessive overhead to produce updated documentation for even minor changes. As a result, documentation tends not to be updated incrementally as would be ideal. Also, at release time, dealing with the production of documentation consumes much more time than it should.

Basically, the approach we have now is that our documentation is separated into Word documents, one Word document per chapter. Already, this limits the ability of people to contribute to the documentation to those who have Microsoft Word or perhaps OpenOffice. Requiring users to have Microsoft Word already goes significantly against the spirit of an open source project in my view. While OpenOffice, in contrast, is open source, I am not sure if it is fully compatible or not. It probably is if all you are editing is text, but may have more difficulty with other sorts of document structures. Further, since the documents tend to be large, it often takes quite a bit of time to load, even though this is partially ameliorated by only storing a single chapter in a Word document. Finally, when it comes time to compile these documents for delivery, it is a tedious process to arrange the correct documents in the correct order without any unexpected issues. Also, I think an issue that has come up in this release that also appeared in this release is that the links in the generated PDF files did not work.

A better approach to documentation would:

First and foremost be able to compile all existing documentation with a single command. There is really no good reason to have so many steps for human intervention, and hence mistakes since it should be possible, in both theory and practice, to have a simple working PDF produced with a single command. Furthermore, there is really no good reason for us to tie our documentation to a proprietary product, like Microsoft Word. Especially since we are an open source project.

Second, we should be able to edit documentation without any software besides a web browser. By easing the overhead of updating documentation, we are much liker to have documentation that is updated more often, to be more accurate, and of a higher quality. I believe that there might be solutions out there that allow the editing of documentation by anyone from a web browser (something like Wikibooks might do the trick, but more research is necessary). If we found a way to allow the documentation to be edited from the browser, this would make it easier to update the documentation as we work and also in response to questions we get from the community. Also, it would allow more people to be able to easier contribute to the documentation, whether or not they have Microsoft Word, whether or not they know how to access our repositories to access the current documentation and whether or not they could figure out how our current documents are structured and whether or not they have write access to our SVN repository.

Perhaps getting documentation that is fully editable from any browser is unrealistic. It depends on the adequacy for our needs of open source projects (like Wikibooks) and also how much effort would be involved to take our current documentation from Microsoft Word format into the more open formats supported by these projects. But at the very least, we should strongly consider at least moving away from solutions that require access to proprietary software and which are error prone when converting from the format in which documents are written into their final form.