Documentation is Not Enough

What's the last thing developers want to do when the sprint is about to end and they have some more code to write? Documentation. What if I told you that documentation, while absolutely required, is not enough?

All of us deal with situations where we are working with software which has little or no documentation (docs) or the docs are way out of date. It's a very frustrating experience. It has happened enough times that the first thing I look for in an open source library or project is its documentation. If the docs are sub-standard, I look for alternatives immediately.

Docs are the backbone of every good engineering team in an enterprise setting. Unfortunately, I have never come across docs that were always maintained, complete, updated, and didn't require institutional knowledge. Moreover, very few docs include assumptions and tradeoffs. If your company has multiple teams and they use a variety of spaces to host their docs, good luck even knowing where to start looking.

The next step up from pure docs is code or automation. Folks believe that if they entomb docs in code they'll have a better time keeping them updated and relevant. The counter point to this thinking, in sometimes hilarious situations, is something I like to call phantom automation. There's this automated process, running on some unknown system, written by who knows or when, that keeps doing its job. Someone at some point knew the problem and how to solve it but they're long gone. Others are left behind to suffer the consequences of this phantom. At some point a hunt begins to identify its location and source. This is an extreme case of "code as docs" but it shows that even code is not an alternative to documentation. It can only augment it.

What's really required is building docs, writing automation around them, and the final step, creating institutional knowledge around these two. More than one person must know, at all times, about the problem, docs on it or its solution, any code written for it, and where and when the code gets executed. Multiple people should be able to answer questions about the assumptions and tradeoffs around it. Teams should carry the knowledge of any future TODOs left at the end of that exercise.

It's all well and good to rely on docs or ticketing systems to manage knowledge but it's the people who must know the folklore. I use Bugzillas and Jiras and others to trace cause and effect. But it's not an alternative to talking to another engineer on the team for an hour to demystify what really happened.

I really love to pair or mob program. It not only helps hammer out a lot of critical decisions before they're made but builds folklore. Code reviews are very poor cousins of mob programming. They are mostly after-the-fact and don't have the retention properties needed to build folklore.

All the stories we hear on podcasts about how UNIX was made or how the internet was built involve multiple people working together to achieve great things. We don't see blog posts linking to bug tickets from way back; we hear people speak. It's the folklore, the myth, the legend that teaches us.

In short, write docs, write code, and build folklore. That's how longevity of systems can be guaranteed with any semblance of quality.