How to Fix Chronically Out of Date Documentation

It seems that every project we run into has missing or out of date documentation. Wikis become stale. Don’t even start me on that out of date README.md file.

It’s almost not worth writing documentation because it gets out of date so fast.

Right?

Wrong!

But you know I was going to say it was wrong anyway, right?

The problem is this: natural language code is not given the same priority as computer-readable code.

What? Natural language code?

That’s what documentation is. Think about it: programming code illustrates a problem, a set of constraints, and gives output in the form of a solution. This is what we usually think of as our work product.

Documentation exists because there is a problem: we don’t know how a business or technical process is meant to work. It explains then what logical steps we need to take in order to understand or implement the project (think readme about bootstrapping a brand new project). The output of the documentation is your knowledge of understanding the process - or a working project that has been properly bootstrapped.

I prefer to think of that documentation as natural language code.

Now, how do we solve the problem?

We make sure all code is written for the project to be considered complete. That is to say, if there’s a bit of code put up for review, where is it’s associated documentation? They’re both important and on the same level. There are thousands of hours wasted by people having to read COMPUTER code in order to understand human processes. Why?

So, how do we keep them up to date? Refer to both as code and make them have the same priority.

Arguments

That’s a perfect world answer. Now, let’s try some common arguments.

Argument: Our programmers are not great writers.

Yes they are. Maybe their grammar isn’t perfect, but it will get better with practice. And, if they don’t have english as their primary language, they can write what they understand in a different language and get it translated. If they can’t explain the process even in their own natural language, then how can you trust their computer-related solutions are correct? That’s a language that none of us really speak directly.

Argument: I need the feature out there - I don’t have time for documentation.

I’ve heard this same argument about all kinds of things - especially unit testing. I can tell you that I personally have progressed to write unit tests pretty fast - and in fact, writing them saves me a lot of time. I can write and run a targeted unit test against my code repeatedly much faster than I can load my program or a web interface and provide the proper user input and measure output each time.

In addition, when you deploy code without documentation, you’re putting a lot of risk on retaining your programmer/talent. Perhaps they forget. Perhaps they are hit by a bus. Either way, now they have to read CODE which is much harder to read and understand than natural language documentation. You’re going to lose much more time later. Was it really worth the risk launching without the documentation?

Argument: There is too much time spent on documentation - things are getting over-documented.

This is a possibility - but it has been pretty rare in my experience. Generally, an equilibrium will start to be found when the culture and expectations are set properly. Remember, we’re not talking about perfect documentation - we’re just talking about non 0% and non-out-of-date documentation.

If you have this problem - and you probably won’t - then you can address it at the time with a slight correction. A nice analogy is a relationship or a friendship. If you never make a friend, they can never hurt you. But the positives very much outweigh the chance of hurt. Same thing with this documentation. If you never document you can never over-document. But generally your documentation is worth more than the pain.

And - you can repair both situations usually. If you are too afraid to make friends, then maybe you have some sickness to deal with. In the same vein, if you’re unwilling to spend documentation time, your project or company is operating while sick.

End Notes

So, write documentation. Keep it up to date. It’s as important as code. It’s a form of code. It doesn’t take that long once you get into it. A proper set of expectations and culture will help make this simpler and easier.