What you say and how you say it

The way you write is just as important as the information you’re trying to get across

The most important thing to remember about documentation might seem obvious, but it’s surprising how many people forget it:

Your documentation needs to explain your product, code, API etc. to a person who doesn’t necessarily have the same level of knowledge as you.

Rule number one of great writing is to think about your audience and write for them. And rule number two? Write like you speak. Let’s dive into both of those right now.

Write for your audience

Your audience may be made up of people with varied levels of expertise, or be a very narrow subset of people with specific knowledge.

Tip: Before you even start writing, take a moment to think about what your audience looks like, and what level of detail they may need.

Depending on what you’re documenting, it might be safe to assume that your readers will understand technical language, or have background knowledge of your topic. In those cases, you can throw in common technical terms, and leave out some basic knowledge that you know every reader will have.

But in some cases, your documentation needs to apply to two audiences — users and developers. Users just want to use your code, and don’t need to know how it works or why you wrote it the way you did. Developers want to contribute back to your code, and they absolutely need that extra context.

If you are writing for a diverse audience like this, think about how you can find balance between explaining the ‘why’ behind your creation for developers, and giving users the information they need fast.

Tip: For beginners, consider spelling out acronyms, avoiding technical jargon, and adding a glossary to your documentation. If you really need to use three-letter acronyms (TLAs), spell them out the first time you use them, and include the acronym in brackets for future reference. Just like I did in that last sentence 👍

Write like you speak, but be direct

The best writing advice works for any kind of writing: write like you speak.

But in documentation (especially technical documentation), it’s just as important to be direct and get to the point quickly. You don’t want to bury key information three sentences down.

Ask yourself: Why are you readers in a specific section? What are their goals, and what information do they need to achieve them? Then do your best to get to that information quickly.

Tip: When you’re writing about something complex, stop at the end of each sentence or each paragraph, go back, and read what you wrote out loud. Did you trip over a word or phrase? Did everything you just read make sense?

If you’re struggling to read your own writing out loud, you should consider rewriting it.

Once you’ve read it aloud, go back, cut unnecessary information and clean up anything that’s unclear. You should end up with copy that sounds like something you would say to your prospective audience in conversation.

Want to see some great examples?

Good news! GitBook has gathered some truly great examples of documentation done well. Go take a look!