Words are Power: Writing Authoritative Documentation

Published Feb 8th, 2018

One of the hardest problems in both Closed and Open Source Software is documentation. How do we convey what the software does? How do we keep it up to date? I could list more but the problems in that space alone are enormous. With this post I want to talk about something I've noticed recently in various bits of documentation and how you can avoid it in your own work.

Often we use words like "Sort of", "Could", "maybe", etc. in our every day speech. It's what I like to describe as hazy language. Yes it implies that things are like that, but it doesn't authoritatively say "This is how it is."

When it comes to every day speech that's totally fine! Your thoughts might be buffering in a conversation, you might actually be describing possibilities, and things that could be, but that's not the language you should be using with documentation.

Your documentation of your projects or those you contribute to are "The Source of All Truth." It's the gospel. When people look at them and read them they should know that "This is it, there's no doubt in my mind that I have to do it this way."

However, many of us write how we talk, we say things how we would describe something to someone if they were in front of us. They're not though! These are documents read by developers at different times of the day and guess what? You're not there. These docs are your proxy to talk to other developers and convey how to use your work!

How do you write your documentation in such a way that it's clear, concise, and authoritative? I've included a few tips below that should help:

If you keep these in mind you should be in good shape. Documentation is hard. Writing docs that empower your users is even harder, but being authoritative on the library with documentation is the easiest win you can have.

Remember, words are there to convey meaning. Documentation is also meant to precisely convey that meaning, so take that tone with the words you choose as well!