What is good documentation, anyway?

Is anyone reading what you are writing?

This is a serious question and one you should be asking yourself regarding documentation.

As product people, we act as the keepers of documentation throughout every stage of the product development process. We didn’t ask for the role, but since product’s principal job is to foster alignment, it’s in every product manager’s best interest to advocate for best practices surrounding documentation.

Documentation is one of the best tools for maintaining long-term alignment and serves as a heuristic to see how the team’s communication holds up. It is one of the few artifacts that weaves its way through the entire product development cycle — even before a single line of code is written. And after a product ships, it becomes critical for engineers and customer support teams.

The perils of poor documentation

Without documentation, our teams end up making decisions that aren’t aligned.  While this might not affect the product today, you can rest assured that you’ll lose a lot of sleep trying to get them back on track tomorrow. 

Those of us who have been around long enough have a story or two in which great documentation saved a launch, a product, or even a company. On the flip side, there are plenty of stories where a few sentences would have saved weeks or even months of work. 

Unfortunately, documentation isn’t sexy. Although it mitigates disaster, it does so quietly. As a result, it’s easy to forget about documentation or even complain that it is “useless.”As a mentor once told me, “No one loves the janitor, even though they prevent catastrophe since it happens in the background.” 

One day, it will be 3:00 a.m. and the world will be watching. In that moment, you’ll want your documentation to be well-organized and useful. That’s what documentation is — a friendly helper in a time of need.

So, why is it hard to get anyone to read it?

Well, since it isn’t sexy, we rarely take the time to give it the care it needs. We end up with documentation that is fragmented, inaccessible, and ad-hoc. In a crisis, these are the worst traits for documentation to have.

As good product managers, we need to change that for the long term health of our products, and we can do that through the lens of visibility, accessibility, and systemization (VAS). 

What is good documentation anyway?

We can’t talk about documentation without being clear about what good documentation is. This is where the VAS acronym comes into play. Good documentation is:

• Visible. You can see an answer when you need an answer.
• Accessible. You are able to get to more information quickly and easily.
• Systemic. Your documentation is always improving within your work system.

Good documentation is visible

Where is your documentation? 

When people are looking at documentation, they are usually in the middle of an anxious moment. This is the wrong time for anyone to be wondering where something is.

With documentation, the answer needs to be first, in multiple places, and shouldn’t require any thought on the person looking it up. Speaking of looking things up, good documentation relies on different ways of making information visible. Images, videos, indexes, and tables of contents are all useful tools to help the reader find their answer faster.

Talk to your team about how they like information to be presented, then organize that information in a way that they can understand. In fact, talk to them about your documentation itself and why it’s important. Remember that documentation is for all types of people, so you should be prepared for different styles and preferences. 

Good documentation is accessible

However, being visible isn’t enough. Folks should be able to get to it, too

There is nothing worse than documentation that is hidden, or even worse, password-protected. Open up your documentation. That’s the easiest way to make it more accessible. 

Once you do that, audit your documentation so that anyone that works at your company can read it. As Nielsen tells us, documentation needs to be plain. No codes, no esoteric messages — just plain language.  You never know who might need to rely on that documentation in a pinch. 

Make it easily searchable. Anyone who wants to read about anything should be able to access it intracompany — full stop.

If the path to help isn’t clear for the level of information, then everyone loses, and your documentation doesn’t serve its purpose. 

Good documentation is systemic

Sure, it’s great that people can access your documentation, but how do we improve it? Do you think about documentation through the product development process, or is it something that is tacked on at the end? 

If the answer is the latter, it shouldn’t be. Your documentation should iterate just like your product. I don’t just mean slapping a changelog on top of your documentation. Whenever you are looking at a feature or product, take a moment with the rest of your team to decide what is useful and what isn’t.

This sounds like a lot and can be whenever you do it for the first time. However, when it happens in every sprint, you’ll see it can be done in as little as an hour. 

Your documentation should have milestones, no different than anything else in your app. 

Documentation is critical

Your documentation functions as a great janitor. At its best, documentation serves as a way to save time and mitigate risk by giving folks an asynchronous method to get the answers they need.

Good documentation matters because both the team and your customers will need you when you aren’t around. However, this won’t matter if it isn’t visible, accessible, or built into your system of product development. And as a result, you’ll see other levers utilized (customer support or cancellation) for issues that are solvable through documentation.