Ian Dees, Tektronix
Software projects are growing in complexity. At the same time, demands on our productivity are increasing. So it’s vital to come up to speed quickly on any given body of code, whether it’s a new third-party library or a neglected legacy subsystem.
Many projects lean on API documents that have been automatically extracted from source code comments. Other teams construct elaborate diagrams that explain every detail of the architecture. While these can both be helpful as a reference, they do little to answer the basic questions about the code: what’s this for? What file should I look in first? What’s this project’s equivalent of a “Hello world!” program?
In this presentation, we’ll use the metaphor of a magazine article to think about ways to help someone learn an unfamiliar code base. That person may be a new hire today, or it may be you, five years from now.
Getting the emphasis and level of detail right are crucial. Everything else, especially the specific writing tool you choose, is secondary. Even so, we’ll spend some time looking at a couple of open-source software packages that may be of help on your quest to produce great documentation.
2010 Technical Paper, Ian Dees, Abstract, Paper, Slides
