Pointed Development

Your Code Is the Only Meaningful Project Documentation

| Comments

Have you a valediction, boyo?– James Cromwell as Captain Dudley Smith, L.A. Confidential, 1997

I recently had the most interesting chat about documentation on the way to the local coffee shop.

My department has been having a lot of discussion around documentation. We’ve been working through software design specifications, functional design specifications, business requirements documentation… all for a single release for a single project, and we have many releases and many projects. It’s a lot of writing and a lot of work and it takes a lot of time. Apart from the specifications, we also have process documentation, corporate mandates and email and wikis and SharePoints and intranets and thousands of Word documents scattered all over the network, not to mention all of the undocumented tribal knowledge that’s scattered throughout the entire organization.

It’s really kind of a mess.

We were talking about documentation in general, and one of the developers mentioned that the functional design specification needed to be updated every sprint in order to give QA the required documentation for testing, but that the time required for updating documentation was far too excessive, that too many details were being captured.

That it wasn’t sustainable. The developers were concerned (and rightly so) that documentation would stagnate as code matured. What good is stagnant documentation? Outdated specifications are rarely useful, or are only useful for their historical insight.

The whole conversation sent up a red flag. We should be generating our documentation, not writing our documentation! The only valid documentation is the code itself!

The fact that we were so concerned about the creation, publication and maintenance of functional specifications indicated a fundamental flaw with the importance we were placing on certain aspects of the SDLC. Yes, we need documentation. No, we don’t need to be writing documentation by hand for every release. Why? It’s impossible to keep hand-written documentation in sync with an amorphous project, just like it’s impossible to code within a team without revision control. Fine, not impossible, but it’s extremely prone to error.

The actual code is the only meaningful documentation in the entire project. TrackAbout had it right: A backlog involved an initial breakdown period which – more often than not – required the developer to read some code! We occasionally referenced a wiki, or interrogated a team member for tribal knowledge… but ultimately, the code itself documented the process.

I’ve already mentioned that I consider the ability to read code one of the most important qualities of a developer. In an agile environment, QA members and developers should be engaged the moment a backlog enters some workable state. Developers should read the actual code – the only documentation that matters – and communicate changes to the QA team.

Ever notice that code comments within a project drift from the actual code they’re commenting? I’ve met very few developers with the discipline to immediately reflect code changes in comments. That being the case, how is your organization ever going to keep a completely separate document like a functional design specification up-to-date with such a fast moving target?

It’s simply not possible. I’ll say it once more: The only meaningful documentation is the code itself. Find ways to automate the generation of your documentation, and consider your codebase the absolute central authority of your codified business processes.