How To Create – and Curate – Effective Documentation

Subscribe to The RSS Feed

There’s more to creating effective documentation than merely gathering information. As a consumer of documentation, you know this to be true. Because you’ve been there. We all have.

At first enthused by the seeming treasure trove of information assembled to guide your learning and project progress, your excitement is quickly dashed as your search for the proverbial needle in a haystack drags on. What first appeared as the holy grail of actionable knowledge becomes a fruitless quest for that one elusive piece of information you need to move forward on a task. Sheepishly, you turn to a more experienced colleague and ask for a lifeline.

You explain that you weren’t able to find what you needed because you simply didn’t know where to look. Or perhaps the flimsy table of contents failed to help you navigate the reams of information efficiently. It may turn out that you actually found what you thought you needed only to discover that it’s out of date and no longer useful. When we experience these situations as information consumers, we tend to lose trust in available resources and stop using them altogether.

When the roles reverse – i.e., when we become creators or curators of information – we need to remind ourselves to balance the effort we invest in creating documentation, so that we can move beyond the mindset that information collection is sufficient.

Keep Documentation Intuitive 

Depending on the amount of information you decide is necessary, be sure to apply a solid structure and logical organization to your documentation. These are crucial elements in the creation process. An intuitive interface ensures ease of access that makes using the information as simple and straightforward as possible. By providing a logical structure to information we might need in the future, we reduce users’ temptation to bypass the documentation altogether, re-establish their confidence, and regain their trust.

Including brief overviews and executive summaries can also aid in directing our users to the most likely places we can find the information we’re looking for. Additionally, establishing a basic visual priority through section titles, text size, and formatting style helps to break up the content into something that can be quickly scanned and absorbed.

Avoid Content Bloat

For our documentation to remain useful over time, it’s important to collect and thoroughly explain key points of information. However, thoroughness doesn’t create value on its own. Documentation becomes valuable as it proves to be an effective tool for sharing knowledge.

Give yourself permission to narrow the scope of content; your users will be happy you did, as precise treatment of the topics enhance their quality and maintain the content’s usability. It’s also important to remember that people learn differently.

While well-considered, thoughtfully curated documentation effectively supports the needs of many of our users, others appreciate in-person communication to nail down the finer details. So consider keeping a list of contacts to serve as go-to resources who can provide additional details that may not be included. This has the added benefit of keeping your documentation lean and more easily navigable.

Keep Documentation Up to Date

Shared knowledge is a continuous and collaborative effort. The products and processes we are documenting are almost certainly going to need to change to remain in use. It’s important for us to remember that if we don’t plan to keep our documentation up to date, it will quickly become a source of incorrect, irrelevant information.

Establish roles and responsibilities for maintaining assigned content. Set a schedule for reviewing and revising the documentation; it’s a simple, effective way to sustain the viability and freshness of your documentation. And assigning tasks to specific individuals provides an easy way for everyone to know to whom they should provide feedback and suggested updates.

Communicate Documentation Updates

By ensuring that we communicate when critical updates have been made to the documentation, we will continue to build collective trust that it is the one best place to find the information our users need.

As we invest our effort in creating and curating intuitive, relevant, current, and timely shared documentation, we create actionable knowledge that is effectively used and, ultimately, trusted.