Ewa There are two major documentation style guides: MS Style Guide and Google developer documentation style guide.
Some companies also decide to create their own style guides and it’s also fine. The bottom line is that it’s important to use style guides. But why?
Table of Contents
Consistency
Style guides allow technical writers to maintain consistency across the documents. It’s normal that every tech writer has his/her own style of writing. Style guides help to tune that down a bit. They do so by making tech writers adhere to some simple principles.
User-friendliness
Style guides created by Google and Microsoft don’t contain only rules and restrictions on vocabulary or punctuation. They teach us to write in a way that’s easily understandable. For example, both these style guides tell us to avoid passive voice. This usually astonishes junior tech writers as well as developers, POs, and other team members who sometimes write or review documentation.
Active voice has many advantages:
- The user has no doubt who should perform an action.
- Active sentences are generally shorter and less complicated.
- The instructions sound more actionable and dynamic.
By using this simple rule we are able to make our text more friendly for every reader and more understandable for all users around the globe.
Read more about making your texts easy to read in this post about writing user-friendly documentation.
Dispelling doubts
Every tech writer – especially non-native speakers – has sometimes questions like Is this the right word to describe it? or Does it sound natural?
For many of these questions, you are able to find the answer in Google or a language corpus. I often check the style guide first: I just use the search box to find the word I’m not sure about.
For example, you are not sure if the chapter about administration should contain the verb “administer” or “administrate”. A quick search in Microsoft Style Guide reveals that they recommend using the word “administer”:
Be careful with external style guides
Style guides like the ones created by Google and Microsoft, tend to change sometimes. A good practice is to check the “What’s new” section of your style guide on a regular basis. However, it’s best to just scan the whole style guide from time to time. This will also allow you to refresh your memory about certain rules or terms.
