November 29, 2005, 12:02 PM — 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
ODF - The Future of Literate Programming?
The Most
-
Will Do Not Track kill the 'free' Internet?
8 comments
-
How to avoid being tagged as a terrorist: Don't pay cash for coffee
6 comments
-
How to kill Web trackers dead
3 comments
-
Even after rewrites, Google Wallet retains gaping security holes, mainly due to Android
3 comments
-
Pickpocketing Google Wallet on Android phones
2 comments
Open Source Month
ITworld LIVE
FlimpVlad_YahP3C7ER has just joined ITworld
itcruld has just joined ITworld
adelphie has just joined ITworld
DariaJones12528 has just joined ITworld
ShojiitagakiXS_tw473572786 has just joined ITworld
jnaze shared iPad apps for book lovers on Email
Cube has just joined ITworld
Gerald Lau has just joined ITworld
ryanhellyer_tw14598449 has just joined ITworld
rasel2011 has just joined ITworld
Mark Cummuta shared IT pay: Premiums for IT skills drop as IT departments reorganize on Twitter
The white paper Guaranteeing 100% Backup Recovery was viewed
CorinaGraham has just joined ITworld
DevelopmentWhite Papers & Webcasts
White Paper
HP NonStop SQL Fundamentals whitepaper
White Paper
Nebraska Medical Center case study
White Paper
Concepts of NonStop SQL/MX
See more White Papers | Webcasts
Answers - Powered by ITworld
ITworld Answers helps you solve problems and share expertise. Ask a question or take a crack at answering the new questions below.
Join Now













