ODF - The Future of Literate Programming?

November 29, 2005, 12:02 PM —  ITworld.com — 

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

ITworld.com

Sign up for ITworld's Daily newsletter
Follow ITworld on Twitter @IT_world

I like it!
Post a comment
The content of this field is kept private and will not be shown publicly.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.
peer-to-peer

jfruh
Apple syncing patent can't come soon enough

pasmith
New Twitter features borrow from 3rd party clients

Esther Schindler
Open Source Changes the Software Acquisition Process

mikelgan
How to set up continuous podcast play on the new iTunes

David Strom
Five important Windows 7 mobility features

sjvn
Guard your Wi-Fi for your own sake                        

Sandra Henry-Stocker
Grepping on Whole Words

 

Sidekick: The Good News & the Bad News
Either way you look at it Microsoft Data Center management did not follow standards or best practices in this failure. In which case it makes me wonder more about the outsourcing of corporate data much less personal data.
- mburton325

Join the conversation here

The Daily Tip

The Daily TipQuick, practical advice for IT pros. Made fresh daily.

Hot tips:

Want to cash in on your IT savvy? Send your tip to tips@itworld.com. If we post it, we'll send you a $25 Amazon e-gift card.

Newsletters

Subscribe to ITWORLD TODAY and receive the latest IT news and analysis.

I would like to receive offers via email from ITworld partners.
By clicking submit you agree to the terms and conditions outlined in ITworld's privacy policy.
Featured Sponsor

AISO founders envisioned a Web hosting company that was environmentally friendly. While the company employed energy-efficient innovations like solar panels, its infrastructure produced unacceptable power and cooling requirements. Find out how AISO leveraged AMD technology to overcome their challenge in this case study white paper.

In this whitepaper, Scalar explores the opportunity to change the landscape with respect to mission critical databases built around Oracle. Leveraging technologies such as Linux, high-end commodity processing power and Oracle RAC technology to architect, design, build and maintain database infrastructure that delivers maximum availability, reliability and performance at a fraction of traditional cost.

On a typical day, weather.com, the Web site for The Weather Channel in Atlanta, serves up between 15 million and 20 million page views. But in September 2004, when back-to-back hurricanes ransacked Florida, the peak traffic on one day more than tripled: over 70 million page views by more than 7 million unique visitors. Read the full success story now.

Marketplace