Software, the sages tell us, should be written primarily for other humans to read and only incidentally for machines to read. I could not agree more. However, as most developers will tell you, project plans are not famous for leaving sufficient time to create documentation. Not only that, but as many software project planners will tell you, developers tend not to queue up to cut good documentation. A deadly embrace forms. Developers, keen to move on to the next thing rather than document the current thing, push the project plan forward as hard as the project planner, sidestepping the documentation question. Comments such as "there is documentation, it is fine.", "the code is simple" or "anyone could pick it up in a day" reverberate around the status meetings.
I have been both the developer and the project planner in this embrace so I know how it works. In the defense of the planners, they have to go on what they are told about the documentation for the system. They cannot be expected to adjudicate on the quality of technical documentation. In defense of the developers, creating documentation is boring to most of their ilk and yes, at the time the code was written, it appeared simple and it appeared that anybody could pick it up in a day.
This problem is, of course, a well worn path. The reason I am walking it is that I suspect a fork in the road is coming. Let me explain. One obvious way to promote good documentation is to make it easier to create the stuff in the first place. A key requirement is to ensure that the documentation and the computer code 'live' in the same place so that they remain 'in synch' with each other. A classic system that does this is Don Knuth's CWEB system for so-called literate programming [1].
Classically, a literate programming system combines a programming language like C with a typesetting language like TeX. To create documentation, you filter the code out of the source files. To compile the programs, you filter the documentation out of the source files.
Now here is the problem. Typesetting languages like TeX extract a price for their great power. A price denominated in a currency called complexity. Using TeX is not a matter of firing up a standard WYSIWYG editor, typing stuff, drawing pictures, creating tables and so on. You need to understand TeX notation to create TeX. On the other hand, you need to know nothing about word processor notations to create word processor documents...
Which brings me to the 'what if' question. What if we leveraged the fact that there is now a non-proprietary standard XML representation for richly formatted office documents called ODF[2]. What if we used ODF compatible tools like OpenOffice[3] to write our programs? How would we extract the lines of code to feed to our compilers? We could just use paragraph styles that indicate �feed this to the compiler�.
For documentation, an embarrassment of riches would then be instantly available. We could use level heading to split up the code/documentation into hierarchical chunks. We could generate tables of contents from these level headings. We could insert pictures wherever we need them along with tables, cross references, index entries and so on. Heck we could even embed spreadsheets, photographs taken of white-boards at planning meetings, the whole shebang.
WYSIWYG literate programming with ODF? I do not see why not.
[1] http://www.literateprogramming.com/
[2] http://en.wikipedia.org/wiki/OpenDocument
[3] http://www.openoffice.org
