A lot is being written about the importance of great technical documentation.
Yet, when you actually get to writing that kind of content, you may find your progress hindered by a lack of specific guidelines.
Fortunately, many tech companies have shared their technical writing style guides online.
To help you identify the best writing practices, we’ve selected six helpful style guides and outlined what makes them so valuable.
Whether you’re working on a technical document or composing your own style guide, this list will help you transform your writing.
IBM Style Guide
The IBM Style Guide covers all writing conventions a technical writer could ever need.
The thorough approach to rules and examples makes this style guide an invaluable resource for creating technical documentation of all topics.
If you’ve ever seen a piece of content produced by IBM, you’ve probably noticed how much value is placed on design.
The IBM Design Language prescribes how visual elements are to be used to represent the company best.
IBM places as much emphasis on technical writing and editing.
The current edition of their technical writing style guide is over four hundred pages long, and as you can assume, it covers everything from vocabulary to rules for writing about computer interfaces.
Reading this, you may now be concerned about how IBM manages to organize so much information without overwhelming technical writers.
The answer lies in leading by example. In the following image, you can find three short directions about avoiding using contractions, abbreviations, and symbols.
As you can see, the style guide also consistently follows the defined rules, helping the tech writers get accustomed to the writing style.
However, the style guide is not only about isolating and dissecting grammatical items.
IBM also pays special attention to using neutral language to make technical documentation accessible to readers globally.
An exhaustive list of preferred and undesirable words lets the writers know what vocabulary to use to keep the language understandable and respectful.
Considering the sheer amount of information contained by the guide, it would be unreasonable to expect writers to memorize all instructions.
Still, the purpose of creating such an impressive knowledge base is to allow users to search for relevant information whenever needed, which is something that IBM's well-organized style guide definitely does.
Apple Style Guide
Apple’s style guide is the perfect example of how language changes over time, even in technical writing.
While the guide primarily focuses on writing about code, syntax, and technical notation, it also highlights the importance of putting readers first by using inclusive language.
You can browse fundamental guidelines on Apple’s developer sites. These snippets present a concise overview of crucial guidelines for technical writing.
For instance, the section about syntax descriptions only has a few sentences summarizing the writing style.
Those interested in more details can download a 225-page PDF enriched with explanations and examples.
In addition to listing standard technical writing conventions, Apple goes above and beyond in their efforts to make each reader or customer feel valued.
The style guide contains instructions on writing inclusively, and asks technical writers to periodically check the guide for updates because language practices change over time.
While most technical writing style guides cover the subject of gender-neutral language, Apple also discusses writing about disability and inclusive representation.
Since writing about software often requires you to use example names, Apple provides names that reflect a variety of ethnicities and genders. Here are some suggestions.
Given name examplesBlair, Etienne, Guillermo, Lee, Mayuri, Priyanka, Shannon, YenFamily name examplesKawashima, Lai, McNeil, Melnykova, Salinas, Sears, Zhao
Apple’s style guide also takes into consideration the fact that technical writing involves using visual elements, and provides clear directions on using screenshots and describing them.
Lastly, as we mentioned earlier, IBM’s style guide has four hundred pages and discusses the minutiae of grammar.
Apple tackles the matter the opposite way and refers technical writers to The American Heritage Dictionary, The Chicago Manual of Style, and Words into Type.
This approach reduces the amount of information in the guide, and lets writers focus on guidelines they can’t find elsewhere.
SUSE Documentation Style Guide
SUSE Documentation Style Guide is an open-source treasure trove of technical writing advice.
Since it was originally created in 2007, the style guide has constantly been updated to keep pace with the changes in technology and language.
Unlike other technical documentation style guides, the SUSE one starts with a message to technical writers.
The note lists four steps for writing effective technical documentation, and these are:
- Defining the target audience
- Researching a topic
- Writing about a topic
- Getting reviews
Each step is accompanied by a brief explanation. So, the guide doesn’t only specify technical writing dos and don’ts; it also helps users structure their writing process.
Another distinctive trait of the SUSE style guide is that it wants your technical documentation to perform well in ways other than providing end-users with valuable information.
For example, this style guide also provides advice for writing SEO-friendly content, helping companies attract organic, unpaid traffic.
One of the tips is to structure content in a way scannable to both people and search engines.
Meaningful title tags and meta descriptions are also noted as powerful SEO tools for external documentation.
Of course, the guide also outlines common technical writing guidelines, such as referencing variable names, inline elements, and more.
These usually vary by company, but you can still check SUSE’s guidelines for inspiration.
The style guide ends with two tables designed to help writers select the appropriate terms.
The first one lists technical terminology, which is especially useful in situations where multiple versions of the same word are used.
This table, for example, lets writers know that kernel space is the only acceptable version of the term, as opposed to kernel-space or kernelland.
Similarly, the second table outlines general vocabulary writers will likely use. For each accepted term, you can find its rejected versions and learn why using them is incorrect.
All in all, SUSE presents a refreshing take on technical documentation guidelines.
The guide may occasionally lack specific examples of what is being described, but the company makes up for that by providing all-encompassing directions for technical writing.
Google Developer Style Guide
If you’re wondering how to organize an abundance of technical writing information, then the Google Developer Documentation Style Guide may be an excellent role model.
Google’s style guide arranges information into readable chunks.
To keep the material even more accessible, the style guide incorporates specific recommendations, along with examples of practices that should be avoided.
For instance, the section about linking instructs writers to put the punctuation outside of the link tags.
The advice is followed by two lines of text representing a good and a bad example of linking practices.
The practice of listing specific examples extends to all sections of the style guide, from language and grammar to HTML formatting.
This approach is especially helpful in the sections where applying vague guidelines can be challenging.
For example, the direction “find a balance in the formality of the tone” may not mean much to inexperienced writers on its own.
However, several examples of sentences with different formality levels make the instruction significantly more understandable.
Since covering every single technical writing guideline would be impossible, Google’s style guide includes additional resources and defines the reference hierarchy:
- Project-specific style guide
- Google Developer Style Guide
- Third-party references
So, if you wanted to write technical documentation about Kotlin using the Google style guide, you’d first have to check the Kotlin style guide and see the project-specific rules.
Then, if you wanted to use dashes, you’d first have to check what the Google style guide says about the usage.
The guides state that only em dashes are allowed. But if there weren’t any rules for that, only then you’d refer to a third-party reference, such as Merriam-Webster.
In other words, this style guide ensures that writers always know where to look for information without overcrowding the original guide with data that may not be universally useful.
To sum up, Google is a tech giant known for its attention to detail in presenting information.
Therefore, it’s not surprising that their writing style guide has a similarly effective approach to outlining best practices and related examples.
Mailchimp Content Style Guide
While Mailchimp’s Content Style Guide wasn’t specifically designed for technical writing, it’s an invaluable resource for all tech writers because of its pragmatic approach to educational content.
You can see that this isn’t an average style guide as soon as you open the home page.
A disclaimer about going beyond basic style points lets readers know they can expect practical writing guidelines rather than strictly adhering to traditional grammar rules.
“We break a number of grammar rules for clarity, practicality, or preference.”
After all, Mailchimp is a marketing tool, so it makes sense to advocate the use of ordinary language.
Mailchimp also brings simplicity into the style guide with an easily navigable table of contents. All the sections are always in sight, allowing for an easy overview of the topics.
As we said, this style guide doesn’t cover the topics strictly related to software.
Still, the outlined principles apply to all technical or educational content, such as release notes or API documentation.
For instance, the guide recommends keeping the sentences in technical content relevant and concise, up to 25 words in length.
An additional tip mentioned here is to create a related article or deck if the writer notices they’re getting too far from the intended topic.
One of the reasons why Mailchimp advocates including only relevant content is the potential neurodiversity of the audience.
Learning new technical information can get overwhelming, especially for neurodivergent people, which is why authors are advised to write focused, succinct sentences.
In line with that, the guide ends with the too long; didn’t read section outlining the most important principles.
So, even if Mailchimp’s guide doesn’t outline directions about formatting code, it’s still an excellent source to study while writing technical documents.
It helps writers organize their content into approachable material that end-users can easily browse.
Microsoft Writing Style Guide
The online Microsoft Writing Style Guide replaces the Microsoft Manual of Style, the style guide whose final edition was printed in 2012.
Users can download the online version for free, which makes the knowledge widely accessible.
The core principle of writing in line with Microsoft’s values is presenting ideas clearly. In fact, the first thing you see when you open the guide is the motto that reads “make every word matter.”
One of the ways you can achieve clarity in technical writing is by steering clear of verbosity. Similarly, Microsoft suggests sticking to basic grammar structures.
“Simple grammar tends to be easy to read and understand, like a conversation. That basic grammar you learned before you were 12 is probably just right for most Microsoft content.”
Considering that overusing industry jargon can damage readability, the style guide also advises using technical vocabulary only when necessary.
It provides a checklist of steps you can take to determine if a term you’ve used is considered jargon.
Still, developers and other IT professionals—the primary target audience for technical documentation—have at least a fundamental understanding of programming concepts.
This is why the guide advises writers to use technology-specific terminology where common vocabulary and explanations take up too much space.
Lastly, Microsoft’s guide provides great materials for writing developer content. There are guidelines for writing code examples and formatting developer text elements.
For instance, technical writers can find a table containing common development elements, Microsoft’s conventions, and examples.
While the conventions from the table are not universal, they can still be an excellent tool for achieving consistency throughout the documentation.
All in all, if you’re looking to write reader-friendly technical documentation, Microsoft’s guidelines could point you in the right direction.
Conclusion
The way you present information can make or break the success of your technical documentation, and, ultimately, the product.
So, if you want to create great documentation, these style guides can help you polish your writing.
Of course, none of the rules we’ve seen are hard and fast; they should be there to assist you, not limit your writing.
