Sunday, September 17, 2017

Documentation needs usability, too

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?

Remember that documentation needs good usability, too. 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.

Finding the right tone and "level" of writing can be difficult. When I was in my Master's program, I referred to three different styles of writing: "High academic," "Medium academic," and "Low academic."
High academic is typical for many peer-reviewed journals. 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.

Medium academic is more typical of undergraduate writing. It is less formal than high academic, yet more formal than what you find in the popular press.

Low academic tends to include most professional and trade publications. Low academic authors may sprinkle technical terms here and there, but generally write in a way that's approachable to their audience. Low academic writing uses contractions, although sparingly. Certain other formal writing conventions continue, however. For example, numbers should be written out unless they are measurements; "fifty" instead of "50," and "two-thirds" instead of "2/3." But do use "250 MB" and "1.18 GHz."
In my Master's program, I learned to adjust my writing style according to my instructors' preferences. One professor might have a very formal attitude towards academic writing, so I would use High academic. Another professor might approach the subject more loosely, so I would write in Medium academic. When I translated some of my papers into articles for magazines or trade journals, I wrote in Low academic.

And when I write my own documentation, I usually aim for Low academic. It's a good balance of professional writing that's still easy to read.

To make writing your own documentation easier, you might also consult the Google Developer Documentation Style Guide. Google just released their 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.

No comments:

Post a Comment