Charles Roth: Writing and Code Samples (2003)

Introduction: a brief polemic. (Or skip to the samples)
A colleague (Doc Searls, editor at Linux Journal) once asked "Why is there no Moore's Law for software?"  I believe that part of the answer is "poor documentation".  Documentation is the most neglected part of all software projects today -- no matter how excellent the rest of the software. 

More precisely, I think what is neglected is what Zen calls "beginner's mind".  I don't mean "writing for beginners"; I mean writing documentation with the same "beginning mind" that the developer(s) had when they started a project. 

I believe that this way of thinking must be applied, fractally, at every level of documentation -- from the user manuals to the individual function or class headers.  Anyone (who's written code) can write details about how a particular piece of code works or is called.  But it's uncomfortable to go back to the state of mind when a project, or even a single function, was part of the formless void -- that part of design that programmers call "nailing jelly to the wall" -- and hold it in our minds (again) long enough to summarize it and write it down.  I've literally seen people squirm in their seats when I force them to do this.  It really is uncomfortable.

The good news is that actually doing it feels good in the end.  It offers closure, and pride in the total work.  (How often have you heard a developer caught between pride in their work, and an uneasy disclaimer about "...the documentation's not really all there..."?)  It can even be a spiritual discipline, for some.  And it honors the sticky, messy, fascinating state of mind we were in when we designed the software in the first place!

Returning to the original question... this is one reason we don't get exponential improvement (in use or re-use) of software.  We don't know the foundations the software was built on!  Without that, everything we do to build on top of a piece of software is guesswork.  Or, at best, it requires time-consuming detective work to reason backwords from how something works to why it works.

OK, end of sermon.  Here are some personal samples of how I've tried, imperfectly, to incorporate this belief into my work, in both documentation and code.