How to write high quality friendly documentation that people want to read
Request another translation
For the last few years I have written a lot of documentation for projects like
Babel or Flow, blog posts, and guides such as these:
I've tried to focus on the way that I write in order to make it more
approachable and more useful to everyone. There are a number of things that I
have learned over the years that I believe makes for high-quality and friendly
Note: Some of this only really applies when you are talking about things
that require tons of documentation. Try to adapt this advice to fit what you
are working on best.
Here they are as one massive list:
- Keep a lighthearted friendly tone. Don't spend time trying to prove how smart
you are. Treat the reader as a close friend who doesn't have a lot of
knowledge about the topic but is very interested.
- Don't assume prior knowledge about the topic. If you want to appeal to a
large audience (i.e. not a research paper) then you are going to have people
with very diverse backgrounds.
- Don't use words like "obviously" or "basically", I promise you will never
need to. Just say what needs to be said in simple straight forward
language. Never ever talk down to people (both of those words do, as well as
- Don't use idioms. Speak using more formal terms that are well defined. This
makes it easier for non-native-english speakers and for translations to be
written. If you do, you won't just knock it out of the park, you'll do a
really good job.
- Use words that are easier to understand and translate (i.e. "list" instead
of "enumerate"). Don't worry that you're being slightly more precise using a
bigger word, think about how it will sound to someone unfamiliar with the
- Keep things brief. Avoid giant paragraphs, breaking them apart into multiple
paragraphs each with a clear point. If you are writing really long
paragraphs, it's most likely that you aren't doing a good job explaining what
- Link to other places in the documentation often but only for additional
information. Readers should not have to navigate through several pages to
find the information that they need about one specific thing. Just inline the
immediately relevant information and link off if they want to know more.
- Reuse the same small set of examples as much as possible, keep presenting the
same problem and building on top of it. Don't make the user keep thinking
about new problems, people can only focus on so many things. If you need to
keep coming up with new examples, you haven't started in a good place, start
over and come up with a better one.
When writing guides...
- Use as many code/cli/etc examples as possible, show the reader what you
mean. This makes things far easier to translate and is generally much easier
to follow than walls of text. Even if you aren't going to discuss the code
directly it's good for giving context.
- Use headings frequently. This breaks things up when reading and often it is
good for linking to specific information.
- If writing with multiple pages, think about how a single page leads into the
next, point the user to the next page and make sure it follows naturally.
- Gently introduce a guide before diving into technical details. This gives
context and readers are more likely to stay engaged longer.
- Tell one story at a time. You can re-explain the same concepts from different
perspectives or for different use-cases.
- Don't clutter explanations with overly detailed examples. You don't need to
implement a game of sudoku to explain how you might use your library with it.
Typically if you have to explain the backstory of an example then it is too
complicated and serves as a distraction from what you're teaching.
- Don't be afraid of foo's and and bar's. Using them removes mental overhead,
it's explicitly saying to the reader "don't worry about what this is, is
could be anything"
When writing api documentation...
- Think about API docs like they are guides on how to use them. Type signatures
for input and output and a vague description isn't enough to be useful.
- Add information explaining the purpose of a group of APIs before diving into
them. Also add any other relevant information or caveats. People are far more
likely to read it this way.
- Use shared terminology with API names, examples, and explanations. Call
something a single name no matter where you are referring to it, and name
- Don't try to solve real world scenarios in code examples if they become any
more complicated than the API already is. Do not implement algorithms, do not
add a bunch of noisy implementation details that doesn't aid the user.
- Keep code examples extremely short. Your target should be ~3-5 lines of code,
every line past that is a count against you. Think hard about the examples
you are using.
- Never use terms that are offensive to any group. There will never be a good
- Do not use gendered terms. Pronouns like he/she/her/him and gendered terms
like actress/actor/waiter/waitress should all be thrown out and you should
avoid using any terms or phrases that don't necessary refer directly to
gender but have gendered connotations. For example, words "pretty", "curvy",
"moody", or "bossy" all refer to women far more often than they do men.
- Avoid examples using people. You end up sounding like you're talking to
children and it's easy to create examples that place one group of people over
another (i.e. "Susan went to her project manager Tim..."). So as a more
generalized rule, use examples that don't involve people.
- Follow other guidelines outlined in documents like the
This is a living guide for myself and others as I learn more about writing
documentation. I hope it is helpful to others in its current state. If you have
any suggestions, feel free to open an issue or pull request on GitHub and let
Have fun writing!