Tips on writing open source documentation

If you’re like most developers, writing documentation is hard. Moreso if you are writing for end-users. How do you approach writing your documentation? If documentation is too difficult to read—if it’s filled with grammatical mistakes, or the vocabulary is just too dense, or even if it’s just too long—then few people will bother to read it. Your documentation needs to reach your audience where they are.

High academic and Low academic

Finding the right tone and “level” of writing can be difficult. I like to refer to three different styles of writing: “High academic,” “Medium academic,” and “Low academic.”

High academic is typical for many peer-reviewed journals, and also common when writing for other highly technical audiences. This writing is often very dense and uses large words that demonstrate the author’s command of the field. High academic writing can seem very imposing to anyone who is new to the field, however.

Medium academic is more typical of professional and trade publications, and often in undergraduate writing. It is less formal than high academic, yet more formal than what you might write in an email message. Medium academic authors may sprinkle technical terms here and there, but generally write in a way that’s approachable to their audience. For example, numbers should be written out unless they are measurements; “eight” instead of “8,” and “two-thirds” instead of “2/3.” But use numbers for exact measures, like “250 MB” and “1.18 GHz.”

Low academic tends to include most email messages or other very informal communication. Here, the goal is to communicate quickly with people who probably understand the issue as well as you do, so a Low academic style tends to be very loose. Where Medium academic authors might use contracts occasionally to maintain an informal style, Low academic writing uses contractions very frequently. Because this writing is very informal, Low academic authors tend to use numbers everywhere, whether or not they are measurements.

Adjust your style

Think back to when you were a university student. You might have learned to adjust your writing style according to your instructors’ preferences. One professor might have a very formal attitude towards academic writing, so you would probably use High academic. Another professor might approach the subject more loosely, so you might write in Medium academic.

The same applies for documentation. When you’re writing for other developers who know the material as well as you do, you can write in a more formal style. But when writing for a more general audience, such as users who haven’t used your project before, you should aim for Medium academic. It’s a good balance of professional writing that’s still easy to read.

To make writing your own open source documentation easier, you might also consult the Google Developer Documentation Style Guide. Google released this guide for anyone to use. The guide has guidelines for style and tone, documenting future features, accessible content, and writing for a global audience. The guide also includes details about language, grammar, punctuation, and formatting.