Document Your Software Project

A session at PNSQC 2010

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.

About the speaker

This person is speaking at this event.
Ian Dees

Software utility player / musical barnstormer / accidental cook

Coverage of this session

Sign in to add slides, notes or videos to this session

Tell your friends!

Short URL


Official event site


View the schedule



Books by speaker

  • Using JRuby
  • Scripted GUI Testing with Ruby

See something wrong?

Report an issue with this session