Docs Hierarchy of Priorities: A Proposal

As a psychologist, I’m quite familiar with Maslow’s hierarchy of needs. It’s an extremely popular framework for human motivation. The hierarchy, often pictured as a pyramid, states that people look for certain things following a certain order: First shelter, then food, then company, etc. As with most psychological theories, Maslow’s is almost certainly false; nonetheless, it provides a very intuitive way of thinking about priorities.

A few days ago, I tweeted a simplified version of a Docs’ hierarchy of priorities. While I am usually wary of technical documentation frameworks, the idea of having a graphical representation of docs priorities, without stating how or who should execute on it, proved too tempting for me to ignore. The following diagram represents my view of the whats and whens of technical writing à la Maslow:

Level 1: Docs are needed and the org knows it

First, an organization must realize the need for documentation, and put someone in charge of the docs, or at least in charge of their content strategy. Without that kind of awareness, which is also the same that content strategists demand of stakeholders, any documentation effort is doomed to fail. Creating docs just for the sake of it, or without knowing who needs them and for what, or where they should be consumed first, is a waste of time, energy, and talent. Treat docs as a product and ask yourself what problems you seek to solve, who the customers will be, and what success will look like. Doing that early ensures smoother measurements, too.

• Associated metrics: Requests for docs, Cost of not having docs

Level 2: Docs cover most features

Docs coverage provides safety. Your docs might be wonderfully written or brilliantly illustrated, but if they don’t cover most of the actual product surface, they’ll lead to frustration. You know when Wile E. Coyote runs into a ravine? It’s the same feeling. When starting a documentation project, your first goal is to cover all the essential features and provide enough reference and explanations for both product and customers to find common ground. How much is enough coverage is up to you to estimate, though in my experience it’s about 80% of the product capabilities. Given the pace of growth in tech, complete coverage is impossible. Aim for most, not all.

• Associated metrics: Docs coverage, Cost of not having docs

Level 3: Docs are useful and fresh

Once you’ve ensured a certain level of product coverage, you want the documentation to be useful and effective, as well as up-to-date. This being a level above coverage doesn’t mean that the docs you’ve published up to this point are garbage, only that the focus wasn’t on freshness and effectiveness. Docs should solve problems and reduce friction. From this point onwards, docs start to contribute positively to the business. Notice that them being well written or having cool visuals is not explicitly stated: Those are all aspects that can contribute to docs being effective, but are not a goal in themselves. In tech writing, as in engineering, form follows function.

• Associated metrics: Increase in product adoption and retention, Decrease in support requests, Lower time to resolution.

Level 4: Docs easy to find and browse

All tech writers know how important information architecture, usability, and SEO can be, though starting from those aspects or raising their priority above quality and coverage can be not only a waste of time, but also counterproductive. Having an idea of what the audience could be and how to organize the docs is reasonable, though it’s impossible to predict how a navigation system might evolve when docs coverage is low or when the impact of docs hasn’t been established yet. An impressive navigation menu that leads nowhere is like an empty presidential palace: We often dream of it, though users would rather read the docs instead. As it happens with other levels, findability and a good IA is an emergent property of docs when done well. Once coverage and quality have been reached, one can start focusing on improving the navigation, moving pieces around and improving their SEO.

• Associated metrics: Web analytics indicators, Search positioning, User research outcomes.

Level 5: Docs look attractive and offer good UX

One day you decide to start a blog, only to spend the entire week looking for a nice theme for WordPress and a font that matches your voice and tone. The same thing often happens with documentation websites: We spend so much time publishing content in them that we’d like to improve their aesthetics a bit, if only to have a good time while spotting typos. Chances are that readers don’t really care about fonts and colors until you ask them, though. While design should never get in the way of readability, speed, and usability, tweaking the color scheme of the code blocks for days on end should never take time away from more basic aspects. Now, if your docs have attained a black belt in completeness, quality, freshness, and organization, why not make them pleasant to the eye?

• Associated metrics: User research outcomes, Social media references, Forks and stars of your documentation theme.

Level 6: Docs are influential

Everyone wants to be Stripe, right? You get there only after acing all the previous levels and then some. Even if your docs are not perfect, a healthy balance of quality, coverage, findability, and good looks contribute to the tip of the pyramid. Perhaps your docs might not win the Nobel prize of literature, but what about their design? Are customers exceedingly happy with them? What’s your secret sauce? Getting here is like getting at the top of Maslow’s pyramid: Your docs are self-realized and ready to share their wisdom with the community.

• Associated metrics: Social media references, Awards, press coverage.

Don’t look up – look forward

Pyramids are not meant to be climbed like mountains. Rather, as it happens with Maslows’s hierarchy of needs, you will find yourself with interconnected progress in each of the areas (levels overlap each other). This is a good thing, as it means that your work is impacting docs quality as a whole. What matters is where you put your priorities: Don’t start from the top, and don’t obsess with getting there. It’ll just happen.