Documentation that adds value instead of collecting dust

Technical documentation. Style guides, user manuals, system documentation, product guides, etc.

You yawned, didn’t you? 

I get it. The general impression of documentation is that it’s rather dry and fairly straightforward. You write about tools, systems, teams, or processes, capturing how they work so that information exists in black and white somewhere, and not just in someone’s head.

I don’t think it’s that simple. Unless you’re writing it simply to check a box on a list, good documentation should be impossible to untangle from the ecosystem that it lives within. It can only be written with a complete understanding of the tools, people, and processes that are at play both within and around the thing you’re writing about. That investigation and understanding is the difference between documentation that collects dust on a digital shelf and documentation that adds value.

For me, writing technical documentation always begins with a series of questions.

Who is it for?

Your audience should shape the language you use, the documentation structure, and where it’s stored and accessed. For new users, you’ll have to define and explain any internal terms or jargon in detail, and highlight the terms that new users will come across the most. Will it serve as a reference to existing team members? You won’t have to worry as much about frequently-used terms. But you will want to consider how to counter any of the biases that long-term team members might naturally build.

For instance, a developer that’s been on a project team for years may have preferred shortcuts that work great for them, but could be more confusing than helpful to someone relatively new to the project.

Working with government partners can add another layer of complexity. Agency employees often work within tiers upon tiers of people. They’re usually shouldering heavy workloads, and trying to work within highly compartmentalized groups that may have little to no communication with one another. These conditions make gathering information a little more challenging, but also give a technical writer the chance to create something that adds value by bridging those gaps.

What are you documenting, and why?

Are you teaching people how to use a tool? Showing the connections between systems? Explaining the logic behind some calculation? What you’re documenting and why should influence the format you use. 

For example, with system architecture, you may want to include a diagram. Process documentation may be a good candidate for a service blueprint. User guides may benefit from video clips. Keeping purpose in mind helps identify opportunities and can keep you from defaulting to only one format. 

Most important is knowing the outcome you want to achieve. What will team members accomplish with this documentation? Does it ensure the team retains knowledge of a system as they go through a high turnover period? Will topic specialists gain more understanding of an application, allowing for a wider scope of work? Will calls to a help desk decrease because users can answer their own questions? The outcome should be your north star, guiding both what does and doesn’t make it into documentation.

How and when will they use it?

The context in which people use your documentation should affect its length and level of detail. In the moment that they need this documentation, what will they be experiencing? Will they use it just once, or will it be a frequent reference for a regular task? What might be their state of mind?

For instance, a new team member will engage with an onboarding guide when they need to get up to speed, but don’t have much work assigned yet. You can afford for your guide to be on the longer side, and fairly detailed.  

On the other hand, an action plan for a system outage will be used by existing team members during an urgent situation. They’ll need to complete specific actions quickly and accurately, maybe in a particular order, likely while stressed. The documentation needs to be clear and concise, making it easy for someone to skim and understand what they need to do.

How do I make sure it stays useful?

This is an area that often gets overlooked, but it’s important to plan for what happens when your documentation is complete. If you don’t put some thought into what happens to the documentation once you leave the team, it can become outdated, and eventually unusable. Part of the documentation itself should be the plan for who updates it and how often.

I’ve found that the best way to make sure things stay up-to-date is to incorporate those updates into the team’s existing processes.

For instance, adding the details about a new feature to system documentation might become part of a team’s “definition of done,” ensuring that the updates happen while the topic is still fresh in mind. This also encourages smaller-scale, more frequent updates, instead of waiting to make a large set of changes a few times a year, long after the team has moved on to other work. Keeping the documentation updated, relevant, and useful makes it easier for your team to stay aligned and collaborate with others.