next up previous
Next: Literate Programming Up: Documentation Previous: Levels of Documentation

The Evolution of Documentation

Amphibians:

In the beginning, just after code first crawled from the primordial soup, documentation was added as an afterthought. Since the code was already finished, documentation was assigned low priority. Consequently, documentation never got done. Nobody could use the code except the developers, and they used it poorly because they didn't remember what they had coded.

Dinosaurs:

Eventually, enough potential users emerged that someone (not the code developer) wrote a user's manual. It was completely separate from the code, and it was a decent description of the user interface for the version of the code that existed five years ago (documentation takes time!). Of course, it was nearly useless to the code developer. Slowly, the documentation and the code drifted apart.

Monkeys:

Realizing that documentation could be a useful coding tool, code developers began to use good coding practices like descriptive variable names and extensive comments. This documentation didn't tend to wander from the code as much as before, since it was stored with the code. There were some problems, however, because the users never looked in the code for documentation. Also, the code developers had trouble crafting equations in the text comments, and there still wasn't an easy way to access the code.

Man:

Sometime after the stone age, code developers combined documentation with coding in a way that allowed them to generate separate source, hardcopy documentation, and hypertext documentation from the same file. This practice, which they called Literate Programming, solved many of the earlier problems with documenting code. Documentation was stored with the code, so there was less ``drift''. The users got a separate user's manual, and the code developers weren't limited to ASCII text for their equations. The hypertext version allowed easy access to both the code and the manual. Life was good.


next up previous
Next: Literate Programming Up: Documentation Previous: Levels of Documentation
Michael L. Hall