The documentation hierarchy of needs

I look at documentation frameworks such as the Diátaxis approach to documentation with a bit of awe. It’s wonderful that a human being was able to concentrate on structuring documentation, come up with a framework, and share it with other people. I’ve used Diátaxis myself; when thinking about documentation, having a starting point helps unblock my thinking.

However, a documentation framework is only useful on documentation that exists. With news such as Snowflake cutting its technical writing team, or AWS tech writers being laid off in 2025, I ask myself how much people care about good documentation.

Most recently, Fabrizio Ferri Benedetti made a post titled What makes docs beautiful? It was inspired by the same question asked in Write the Docs. I do like the question; what does make documentation beautiful? How do we measure value, and do we value beauty? But then, I am suddenly reminded of companies where writers are constantly having to meet ever-shifting business requirements. Beauty often takes a backseat to functionality—assuming “functional” is even attainable!

If you lack the time to make your docs beautiful, cannot stop and think about documentation frameworks, or cannot even write all your docs, how are you supposed to feel? What is the right goal to reach for? I think there is a useful way to look at the question.

A new Hierarchy of Needs

Maslow’s hierarchy of needs is a motivational theory in psychology. The hierarchy is a five-tier model of human needs, often depicted as levels within a pyramid. Needs lower down in the hierarchy must be satisfied before individuals can attend to needs higher up.

Documentation isn’t a human, but it relates to human concepts. We can try to define things that documentation needs, and I think it’s possible to order these things. It could look a little like… this:

The four tiers correspond to these questions:

1. Existence: does the documentation exist?
2. Usefulness: is the documentation useful to its readers?
3. Accuracy: is the documentation correct?
4. Elegance: is the documentation beautiful?

Let’s break these down a bit.

Tier 1: existence

Does the documentation exist? I certainly hope it does, but truth be told, the documentation doesn’t always exist.

Imagine you buy a shiny new thing. You want to use the thing. The thing is hard to understand, so you look for a manual. There is no manual. You go back to the thing, determined to figure it out. You get frustrated. Maybe you figure out the thing, maybe you don’t figure it out, but you had absolutely no help along the way. There’s bound to be frustration.

Maybe there’s a time crunch. Maybe there are too many deadlines. Maybe there are too few writers, and too many demands. Whatever the reason may be, a lack of documentation is a failure state; a contract between user and product has been broken, as there is no way for the user to get the information they want. While it’s true that lack of documentation can be buffered by a good support team, or a search engine, something still went wrong.

So yeah, first things first: write the damn docs.

Tier 2: usefulness

Is the documentation useful to its readers?

If documentation exists, but isn’t useful to its readers, then why does it exist? If someone spent their time putting words to a document (or generating it with AI), hopefully it has some use! If I went looking for an answer to a product question, but the relevant page didn’t have my answer, I wouldn’t be happy.¹

One could argue that useless documentation is worse than missing documentation, by stating that “missing documentation won’t mislead a reader.” I think that’s not quite true, on the basis that useless documentation shows at least some effort was put into creating words. Even if the words don’t help the reader, we at least passed the first hurdle: writing.

Bear in mind that usefulness is not a yes-or-no question. There is a spectrum of usefulness, which is another reason why this tier is above existence, to me.

Tier 3: accuracy

Is the documentation correct?

When I first thought about a docs hierarchy of needs, tiers 2 and 3 were on the same level. I no longer agree with my first thought, for two reasons:

1. Correctness is a spectrum.
2. Something can be useful without being accurate.

We should ask ourselves what “accuracy” or “correct” means, especially in the context of usefulness. I could certainly write documentation that gives wrong instructions and frustrates the reader. That would make the documentation inaccurate/incorrect, and arguably useless. But what if I simply failed to update a page? That page would no longer be accurate, but it could be useful if it teaches the reader something.

In short, I think it’s possible for something to be useful while being inaccurate or incorrect. This argument walks a fine line, but I will back it up with stories of incorrect video game walkthroughs that still helped me figure out where to go in the game.

Tier 4: elegance

Is the documentation beautiful?

If your documentation exists, is useful, and is accurate, you’re in a good place. You can now think about how to make it even better: improve the user experience, apply framework knowledge, or just make it look nice.

Go read Fabrizio’s article and think on it some more.

How to use the hierarchy

I don’t consider this hierarchy to be an excuse to avoid upper tiers. Lacking documentation is not an excuse to write intentionally misleading information, and nothing prevents us from thinking about beautiful docs ahead of time. The real world is not as neat and clear-cut as the image of the hierarchy.

That said, I think this hierarchy gives some perspective: we can allow ourselves some grace when we find ourselves unable to reach higher tiers. To me, someone who cannot make their documentation beautiful because they’re still struggling with information accuracy shouldn’t feel bad. If said person can’t even finish writing all the documentation, then that should definitely be their focus.

I find it could also model a learner’s path:

• Learn to put ideas on paper.
• Then learn what makes those ideas relevant to people.
• Then learn to watch out for, and correct, mistakes.
• Then learn how to make everything pretty.

If you’re at the point where you have learned of (and can afford) beautiful, elegant docs, I hope things are going well, indeed.