You cannot write good documentation without a clear plan.
Does your documentation seem different depending on who writes it? Does it sound too wordy? Do customers still call you to ask how to do things explained in your documentation?
If the answer to these questions is yes, you need a technical writing style guide.
A style guide is a blueprint that helps you write better documentation that delights your users. It will make your work much easier by giving you a framework for consistency. However, coming up with one from scratch is hard work. Thankfully, there are lots of high-quality open-source style guides out there.
This article gives you the top technical writing style guides you should know in 2022.
First on our list is the Technical Writing Guideline by Digital Ocean. It focuses on technical writing for software engineering and server administration. The 3-section guide covers style, structure, and formatting.
The section on style gives you direction on how to write comprehensive documentation for readers of all experience levels. For example, they recommend that you explicitly include every command needed to accomplish a task when writing tutorials.
The Guidelines also suggest a particular structure for technical articles. For instance, they suggest that you write an introduction followed by an optional goal for the write-up and a list of any prerequisites required to follow along. Afterward, you explain the steps needed to accomplish the tutorial’s objective, then a conclusion at the end. Following these recommendations will make it easier for you to write consistent documentation.
It even comes with a handy markdown previewer that you can use together with the formatting section of the guide.
The Google Developer Style Guide provides editorial guidelines for writing clear and consistent Google-related developer documentation. But you can adapt it for your use case.
The Highlights section of the guide gives you pointers on how to write accessibly and for a global audience. It also has valuable tips on language and grammar, advising the use of an active voice that clarifies who is acting. The style guide gives you a wordlist that lists words that you should avoid. The wordlist also offers alternative suggestions.
The Google style guide has a reference hierarchy that includes project-specific style guides and third-party references. It prescribes The Chicago Manual of Style for nontechnical style and the Merriam-Webster dictionary for spelling. Overall, it is a style guide you can use for many projects.
Microsofts take on style guides is a thorough guide to writing style and terminology for all computer technology-related communication—whether an app, a website, or a white paper. It emphasizes simplicity, minimalism, and friendliness.
Microsofts Style Guide is referenced by many others, including Google. It covers everything from code examples to writing for chatbots. The broad scope of the writing guide can be a disadvantage, though, because of its size. When downloaded as a PDF, it’s over 1000 pages long!
A shortened version is available in the form of Top 10 tips for Microsoft style and voice. The tips summarize the Microsoft writing style guide, so you get up and running quickly.
Smashing Magazine’s version of a technical writing guide is a condensed style guide focused on blog posts. It shares tips and techniques that help make an excellent technical article or blog post.
The foundation of the technical writing guide centers around the audience. It stresses practicality and readers being able to act on the insights gained from technical articles.
The essence of the style guide instructs you on how to structure the elements of your blog post, including the title, introduction, body, and conclusion. It further provides instructions on the formatting of images and code samples, links, headings, and the use of jargon.
The Institution of Engineering and Technology is a multidisciplinary professional engineering institution dating back to 1871. They have a concise but comprehensive technical writing guide of only 12 pages, making it an easy read.
It covers the most important aspects of writing a good technical document. It starts with instructing you to determine your objectives based on your audience. Then, it recommends how to format your technical report and write it. Instructions on including diagrams and maximizing their effectiveness are given to you.
The IET Guide concludes with a list of resources, one of which is “10 laws of good report writing.” You can refer to this quick checklist with tips to improve your technical documentation.
Consistency is essential in technical writing. All the above style guides help you to achieve consistency. Your report should be consistent in voice, structure, and formatting. Now you are ready to pick a style guide and write excellent documentation!