10 Technical Writing Style Guides You Can Use

Great US soccer player Mia Hamm famously said, “It is more difficult to stay on top than to get there,” which suggests that consistency is a highly desirable trait. In the field of technical writing, consistency is crucial because it provides the sense of confidence and continuity that every tech product needs to engage a user base. Also, consistency creates opportunities to build communities around technical documentation.

How do you make your technical documentation more consistent? One of the first steps is to adhere to a technical writing style guide. Itself a piece of documentation, a style guide defines communication standards for any tech document that you or your team will produce. It usually covers the voice, structure, and technical conventions (such as the format of the text, audio, and images) used in the documentation.

Since style guides cover so much ground, they can be a chore to create from scratch. Fortunately, many companies make their own technical writing style guides available publicly, so you can analyze their strengths as you create your own style.

Want ideas for your next blog post?

Download 50 Winning Ideas for Your Startup's Blog

Draft.dev Style Guide

Draft.dev Technical Blogging Style Guide is a good place to start. It’s used by several technical writers who cover a variety of topics, mainly because it sets down the basics of style decoupled from any context that’s too specific. This guide breaks style into the following four sections:

• Voice: It recommends using the second person (you, yours) to engage the reader and establish a clear point of view.
• Content: The guide recommends a certain structure for blog posts and demonstrates how to support claims with evidence while avoiding plagiarism.
• Conventions: This section sets standards for formatting, such as using Markdown and how to add images to a post. Communication: In this section, Draft.dev emphasizes the importance of keeping in communication with the editor or publisher you’re working with and letting them know of any roadblocks as you write.

As you can see, it’s a technical blog post about how to write a technical blog post, a nice meta style guide.

A List Apart

A List Apart Style Guide is an example of a valuable, reader-centric, but more informal style guide. It offers advice about text formatting, assets like images and author bios, and some notes about how to refine the content itself.

One of the more unique features of this style guide is its discussion of the use of metaphors. A List Apart advocates clarity first. Finally, it suggests following the Chicago Manual of Style and Fowler’s Modern English Usage as principal references for proper language usage.

DigitalOcean

DigitalOcean’s Technical Writing Guidelines is a three-section tutorial about how to write compelling technical articles for their Write for Donations program.

While this guide focuses on clarity and quality, there’s also a companion technical best practices tutorial, which offers standards for how writers should discuss the tech they’re writing about (ie, how to write about installation, how to offer troubleshooting tips, and what to do with long scripts).

The four sections of the guide are:

• Style: This is further split into four sections that cover clarity, level of detail, completeness, and tone. It encourages you to write for all technical levels by avoiding assumptions of previous knowledge, giving context for code, and writing “friendly but formal” pieces that show respect for cultural differences.
• Structure: DigitalOcean’s guide is very specific about desired structure for their articles. This section includes examples for various article types and includes some ready-to-use templates.
• Formatting: This section outlines how writers are expected to format their work, which is an extended version of Markdown. It provides examples of supported extensions.
• Terminology: DigitalOcean has established some conventions for writing examples, such as a standard default username, default hostnames and domains, and how exactly to indicate to readers where they should alter text with their own input.

The DigitalOcean technical writing style guide is easy to read and very focused on system administrators and software engineers. The terminology section and linked guides for best practices and code of conduct go a long way toward guaranteeing a high level of quality in the writing.

SUSE Documentation Style Guide

SUSE Documentation Style Guide is a comprehensive and detailed guide to updating documentation for well-established software products like SUSE’s. It starts with simple but powerful advice: define your audience. This sets the level of expertise assumed for the reader and the context in which the documentation will make the most sense.

The guide provides the three following key points about the content itself:

• Avoid promising future features, which are not relevant to the current stable product.
• Include warnings on features scheduled for deprecation.
• Clarify the status of unsupported features before documenting them.

The guide includes more useful details, such as conventions for terminology used in examples (similar to DigitalOcean’s Terminology section) and how to format various content types, like manuals, books, and articles. The defined format is GeekoDoc/DocBook markup language, and the guide includes an extended description of its tags.

The IET Guide to Technical Report Writing

The Institution of Engineering and Technology (IET), an organization that’s over 150 years old, provides a concise guide covering many important aspects of technical writing. Its first section provides 10 laws of good report writing, which you should definitely keep close when you write. Spoiler alert: The first and last laws are the same—write for your readers.

The guide’s next sections complement those ten rules, with discussions about:

• Objectives: determining why you are writing and who you are writing for
• Format: how to structure your writing and reference citations
• Writing: the nitty-gritty of writing, including sentence structure, what a paragraphs does, and striking the proper tone
• Diagrams: determining proper placement and facilitating ease of understanding
• Finishing the report: polishing the piece with summaries, tables of content, and proofreading

In the Writing section, the example about the use of commas is worth noticing for how precise the guide can get:

The engines, which were in perfect running order, had been tested previously. (all engines were in perfect running order and had been tested)

The engines which were in perfect running order had been tested previously. (only the engines in perfect running order had been tested)

Finally, the guide suggests some references such as the Oxford Guide to Plain English and Writing for Engineers (Macmillan Study Skills).

Apple Style Guide

The Apple Style Guide contains valuable information you can use across many contexts, including instructional materials, technical documentation, reference information, training programs, and user interfaces. It also references the Chicago Manual of Style, The American Heritage Dictionary, and Words into Type.

The guide covers a wide variety of editing minutiae, including units of measure, technical notation, a large glossary of terms for proper usage, and links to related resources. The “International style: Overview” section includes tips on writing for non-native English readers, something that’s important to consider especially in technical writing.

GitLab Documentation Style Guide

GitLab uses the same guide for the members of the GitLab team and its community contributors. The GitLab Documentation Style Guide is a living project with constant evolution, which prevents information silos.

The style guide is managed like a software project, with source code. It includes a set of tests that cover:

• The writing and structure of each article
• Links in the content
• Assets in the content

GitLab’s guide references other technical content guides (Google and Microsoft, also covered in this article) and emphasizes the documentation-first methodology approach of the company. This implies that the technical documentation is the single point of truth for the implementation, usage, and troubleshooting of the product.

You can find the specifics of GitLab’s writing style in the Communication section of their team handbook, which defines thirty-seven rules covering a variety of topics, including the use of active voice and how to properly capitalize GitLab.

Google Developer Documentation Style Guide

The Google Developer Documentation Style Guide provides a full set of solid practices for producing technical documents. The guide also acknowledges that many projects under Google’s umbrella might have their own specifics, and it establishes a reference hierarchy that prioritizes the project’s own standards over the common guide.

The guide is very dense and has several sections, so I’ll just highlight a few here:

• Accessibility: This covers not only the voice and tone of the documents but also keyboard navigation tips, support for screen readers, inclusive language, and the use of HTML for formatting.
• Language and grammar: This section establishes common rules for writing. There’s some interesting advice to avoid anthropomorphizing software products and how to use specific verb forms in reference documentation.
• Linking: This includes best practices for readable links.
• Computer interfaces: This section pays special attention to Application Programming Interfaces (API) documentation guides.
• Markdown versus HTML: The guide posits that HTML is more expressive than Markdown, even if the second is easier for humans to read.
• Names and naming: This section explains naming conventions for filenames, domains, trademarks, and more.

Mailchimp Content Style Guide

Mailchimp has a public Content Style Guide, which includes a technical writing section for tutorials and guides. It suggests some useful questions to determine the audience of the article, such as the following:

• Is the reader a prospective user, a new user, or an experienced user?
• What is the goal of the user? To complete a task? To research a topic?
• Is the user in the middle of a task? Are they in a hurry? Could they be frustrated?

Your answers will point you to a template with suggested structure. The document also includes guidance for other types of writing, such as legal content, social media, email newsletters, and more generally helpful advice on writing for translation accessibility. Finally, the “Too Long; Don’t Read (TL;DR)” section is a useful cheat sheet for the larger guide.

Microsoft Writing Style Guide

Many other sources reference the Microsoft style guide as a source of answers for technical writing. Some reasons for this include its wide scope (which covers writing content for chatbots and virtual agents), its content and design planning, documentation about scannable content, and how to select words to improve readability and comprehension, among other useful information.

But the heart of the guide is in its definition of voice:

“The Microsoft voice is how we talk to people. It’s the interplay of personality, substance, tone, and style.”

The Microsoft brand voice has three clearly defined attributes:

• warm and relaxed
• crisp and clear
• ready to lend a hand

You should explore the entire guide to check how these attributes are expressed consistently in each section (creating a scripted chatbot? Writing content for a responsive device?) and take note of how the tone can vary depending on the context of the documentation. Your own brand voice should be distinctive and tell your readers what to expect of your company.

Conclusion

After reviewing all the referenced style guides, you may have noticed three common elements:

• Know your audience and write for them.
• Set your own voice.
• Keep it simple, short, and clear as possible.

This advice is not enough to create a full-fledged style guide, of course, but rules for details like format, glossaries, and standard structures can evolve with time. A good starting point is to take the best parts of the resources available and build your own from there.

By Nicolas Bohorquez

Nicolas Bohorquez is a data architect at Merqueo, has been part of development teams in a handful of startups, and has founded three companies in the Americas. He is passionate about the modeling of complexity and the use of data science to improve the world.