Imagine your team having to go through every problem you went through, just to fix each error that comes up. Having to guess the procedure for doing anything at all. Your clients having to guess what to do, or how to use what you built for them.
That is what documentation is for. Structured text, written to explain how the thing you built actually works.
It is a fundamental part of any product or company, and usually the first thing left aside. If you create digital products of any kind, Notion templates, courses, anything, you have to write documentation.
I get it. Writing documentation is tedious and annoying. It is not fun. But boring as it is, it has to be done. It makes life easier for users and creators alike, by solving or clarifying things before they become problems.
Dani and Alejandra do a great job with the documentation for the NOXEN templates.
Here are a few tips to raise the level of your documentation.
1. Start by asking about the reader
Documentation is not written for fun, for status, or out of obligation. You write it to make it easier for people to use what you built. It is an instruction manual, basically.
Documentation IS FOR THE USER.
The simplest way to start is to ask yourself:
- What does my user need?
- What are they trying to achieve?
- Where can they get confused, or get it wrong?
- Does the user actually need to know this?
- How can I make the task easier for them?
2. Write less
Nobody reads documentation for fun. Users want to find something specific, fast. Write the least you can to make the solution, the behaviour or the problem clear. Do not go beyond what is strictly necessary.
Conveniently, writing less is exactly what you want to do with a task as boring as writing documentation. These tips are good for the user and for the creator alike.
3. General ideas first
As you answer the questions from the first tip, inside each step of your product or company, you will naturally start to see themes. Parts of your own product that stand clearly apart. Write them down. They are the backbone of your documentation.
Every time you find a theme, ask yourself the same questions from the first tip. You will find sub-themes, as deep as you need to go, until the answers are as short and concise as possible.
It is easier to build documentation going from the general to the particular.
Topics help people navigate. One huge block of text is hard to move through, and hard to find answers in. Split it into topics and people can scan titles and subtitles that point them towards what they actually need.
4. Keep it casual
If you do not know how to explain something, try explaining it out loud to someone as an exercise to unblock the ideas. If you can then write the documentation in that same language, the way you would say it to someone in person, do it.
I know that is not always possible, but a conversational tone makes anything easier to understand. It takes the pressure off, and it makes the whole text easier to write.
5. Readability matters
We touched on this in tip 3. Documentation should never be one huge, boring block of text.
You bore the user, you confuse them, and you put them off reading the important information you spent time writing.
If you have several points inside a paragraph, break them into lists. If hierarchy matters within those points, use a numbered or lettered list.
If there is a particularly important piece of information they need to notice, use a blockquote, or a different style, like a Notion callout.
Splitting with headings matters too. Keep ideas as small and concise as you can. Write as little as possible. Be direct, clear and concise.
Avoid adjectives and connectors. Use a full stop instead. Rather than "It is extremely important that you do this in the following way:", write "It is important to do it like this:". Better still: "The right way:"
Whenever you can cut a word, cut it without mercy.
6. Documentation is not a magic wand
If something does not work, explaining it perfectly will not make it work. It matters to tell the difference between mistakes the user can make and fix, and fundamental problems inside the product or the company.
The goal is to write as little as possible, and to have as little as possible to explain. The fewer errors and edge cases there are, the less you have to write.
In other words, the best documentation is a product or a company that works perfectly. Utopian, I know, but always worth chasing.
Conclusion
Those were the 6 tips to improve your documentation. They work just as well as tips for writing articles online.
I know that explaining what we already know can be annoying, especially if you hold the idea that a product should be usable without any explanation. In many cases, that is impossible.
Well written documentation saves your users time and frustration, leaving room for them to like you even more. It also saves you time and customer support resources.
Any way you look at it, it is a win-win.
If you have written documentation before, I would love to know. How do you do it? What tip would you add to the list?