I can see the beauty of mathematics…You can hold infinity in your hands

Programmers write code for a living.  Everyone who writes about programming agrees that programmers need to write more than just code, but this dramatically underestimates the level at which we as a profession should be writing.

It’s become a mantra to “show me the code” but the code isn’t always enough.  Code is a slippery and imperfect representation of the a particular programmers mental model spelled out in the language of the his or her  tools at a particular point in time.  This references changes meaning changes as languages and  frameworks changes, and the programmers working on it change.  Codebases live on, 2,5,10 years past their intended use.  We talk about producing literate code, testable code, readable code, but imagine code being written now viewed from the vantage point of a programmer 10 years from now.  I see it as most likely looking like COBOL appears to most programmers today.

This isn’t writing documentation for the codebase, comments inside of the code, or lists of features and technical specifications.  The truth of the matter is, useful though all those things may be, people don’t read them unless it’s absolutely unnecessary to solve a particular problem with your software. The kind of writing I’m talking about is crafting the story of what your software was intended to do, and to tell the origin of how that software was written.  It’s telling about the technologies used without diving into technical details by describing how they are being used to solve a particular problem.  In fact, a good litmus test to ask about whether or not something belongs in this type of document is “would a non programmer find this useful?”  If so, you’re probably on the right track, if not, keep writing it but put it in one of the aforementioned types of documentation.

Good writing isn’t boring, and it isn’t always entirely efficient.  That’s okay.  Developing a voice and keeping it light means someone might actually read your writing, rather than using ctrl-f to get to the point immediately.  Source control allows you to track the development of software over time, so too should the writing I’m describing document the changing goals and trials, both technical and business specific that the software is adapting to solve over time.  For a completely contrived, and short example:

As the load began increasing in our application and we reached a dozen servers we started having serious concerns about how to quickly get messages between the different parts of the application.  We opted to deploy the third party NServiceBus library as a quick and easy way to pass events between the different parts of our product.   This gave us a stable way to reliably queue up messages to ensure that the email system always sent out responses after the customer sent in an order and prevented embarrassing situations like last week when a silently failing service meant four people didn’t get their Friday deals email until Sunday morning…

This kind of documentation helps everyone.  It gives the business people an idea of how the application is working, it gives future programmers an idea of what problems were being solved when features were being written and it adds to the corpus of knowledge that sales, and management can use to better understand what the software team has been working on.  For consulting, this type of writing can quickly clear up unclear points that can otherwise get glossed over in discussion.  I’ve found that misunderstandings that continue for days during verbal discussion often get immediately highlighted when someone puts down their model of a situation into a problem.  Unlike more specific technical documentation, when paired with a time and a date this piece of writing never becomes outdated it’s just one more thing that paints a picture of how an application came to be what it is today.

The critical point in all of this is that only the people who are intimately involved in writing the application can write this kind of documentation.  Our frequent failure to do so is a contributor to engineering’s too often strained relationship to management and business, and it doesn’t need to be this way.  We can do better, and we can start doing so by communicating our work in a way that everyone else can understand and appreciate.  Write it up, stand up, and be recognized.