6 Rules of Good Documentation

I’ve been a documentation junky since I worked at The Barbarian Group around 12 years ago. The company, and specifically Rick Webb one of the founders, had done a meticulous job recording its history and culture. I, and others, found all that writing to be an incredible way to help ensure that the key ideas, frameworks, and values of the organization (aka the building blocks of culture) carries on through years and people. Since then, in my course of company-building, I’ve tried to write down as much as possible and have spent a fair amount of time thinking about how to use documentation to record, communicate, and shape organizational culture and process.

My goal for this document is to try to communicate some of the best-practices I’ve learned over the last decade-plus. These ideas have shaped both how I think about building companies, and also have inspired some of our ideas about how to build the Variance product. There are three main themes I cover in this post:

• Why writing and documentation matters
• Why it’s especially important in remote contexts
• How to write good documentation

Why writing and documentation matters

Writing scales incredibly well. 

It can be read at any time by an unlimited number of people. Media theorist Neil Postman once said, "The act of reading a book is the best example of distance learning ever invented because reading not only triumphs over the limitations of space and co-presence, but of time as well." 

Inside a company, writing can serve many purposes:

• Writing to communicate. That’s what’s happening here.
• Writing to converse. Thanks to new tools, writing isn't just static, it's a thing people can comment on and edit publicly.
• Writing to think. There's a saying in law—"does it write?"—that speaks to the clarifying role writing can have in the process of thought. Forcing yourself to articulate something in writing lays bare how clearly you understand it.
• Writing to archive. Companies are a sort of shared brain. The better that brain functions, the better the company functions. Having a shared archive of ideas, arguments, and communications and ensuring that archive is searchable can help ensure that brain functions at as high a level as possible.

Documentation, in many ways, is just a business word for writing. We document ideas, frameworks, and processes as a way to allow others to build on top of what we learn. There is real value in the sharing of a trick, technique, or model that will save others time.

Why it’s especially important in remote contexts

So what about remote?

When we were doing our initial research interviews for Variance in the summer of 2019, one of the comments that really jumped out at me came from a former Google employee who said that the biggest determining factor of success at the company was who you got sat next to when you started. That’s because for a long time companies have relied on culture to be communicated orally: letting the ways of the company be passed down from employee to employee either formally or through osmosis. Unfortunately a) that was never a particularly good way to do things and b) in a more remote world the osmosis approach becomes virtually impossible.

How to write good documentation

So now let’s get specific and talk about how to do documentation right.

Here I’ve got my six rules of good documentation. Good documentation is ...

1. Fit for context
2. Clearly written and to the point
3. Visual where possible
4. Skimmable
5. Up to date
6. Discoverable & Tracked

Fit for Context

First thing, not all documentation is created equal. I really like this framework inspired by Daniel Procida for thinking about the types of documentation depending on whether someone is trying to do something or understand it and whether it’s a self-directed activity or one that’s guided by someone else. 

Inside your company you probably have a little bit of all this stuff, and the first step to making new documentation is figuring out which of these quadrants you are writing for. That’s rule number one of good documentation (and any writing for that matter).

This presentation started as a doc, which will then be archived in Notion (our wiki-like thing). It’s squarely in the bottom-right quadrant.

Clearly Written and To The Point

Like the first rule, this one isn’t actually specific to documentation. Good writing is clear writing. As William Strunk Jr. wrote in his famous writing manual Elements of Style:

Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all sentences short, or avoid all detail and treat subjects only in outline, but that every word tell.

Get to the point. Make your point. And get out of the way.

Visual Where Possible

Now we’re starting to get a bit more specific to documentation. It’s particularly important that you utilize visuals where possible when explaining things to people. It’s partly because everyone learns a bit differently and also because it gives you a second chance to make your point (more on repetition in a bit). 

Take the quadrant graphic above. It would be one thing to explain the different kinds of documentation and a whole other to actually show them. What’s more, the examples of real documentation in this presentation serve a purpose to bring ideas to life in a way just words can’t always do.

What’s more, when it comes to documenting software, using moving visuals (either animated GIFs or videos) can also help make things immensely easier to understand. Sometimes words just won’t do.

Skimmable

I once had a boss who wouldn’t look at any Keynote presentations unless the slides were indented properly to indicate sections and subsections. While it seemed a bit crazy at the time, his point was that you need to design things to be easily skimmed. Write the Docs, which makes an excellent repository of documentation about documentation, writes, “Structure content to help readers identify and skip over concepts which they already understand or see are not relevant to their immediate questions.” That means using headings, links, lists, paragraphs, and bolding amongst other things.

Even as I’m writing this document I’m building an outline by using heading tags.

Up to Date

This is both one of the most obvious and forgotten rules of good documentation. Documentation that is no longer correct can be worse than having no documentation at all. 

It’s impossible to trust documentation that is routinely out-of-date so developers end up going back to the humans that contain the most update date information. This reinforces the notion that writing anything but code is a waste of time and keeps system knowledge locked safely away in human brains.

So how do you keep documentation current?

1. Set a check-in date for all documentation (either in the tool you use or at least in your calendar/task management system)
2. Split up documentation when you can so you have to update in as few places as possible
3. Make it easy for people to give feedback and encourage a culture that fixes or flags mistakes in documentation

Discoverable & Tracked

Everyone knows the saying, "If a tree falls in a forest and no one is around to hear it, does it make a sound?"

Well, there’s an equivalent saying in documentation: “If documentation never gets read is it documentation at all?”

There are really two parts two this question and without both of them in place there’s no way to know the answer. The first is about making sure your documentation is discoverable:

• Easy to find
• Categorized
• Sharable

The second piece, though, is about tracking those things to understand if they’re actually happening. Because, what may seem discoverable to you, turns out not to be easy to find for anyone else. To this latter point, you are somewhat at the mercy of the system you use for documentation. Tools like Confluence offer view counts which can help bring to light what documentation is being used and what isn’t. For the stuff that’s being used heavily, it’s even more critical to ensure it’s up to date. For the stuff that not, you’ve got to figure out why and either connect it to something else or dump it and integrate it if it’s important.

Documentation = History

In the end, your documentation is your history. The more precise, up-to-date, and detailed that history is—plus the more people that contribute to the “story” that history tells—the more likely it is that you will be able to recognize/change what doesn’t work and replicate what does. Following these best practices along with some basic writing guidelines can help take some pressure off newly remote teams.