9 Technical Writing Style Guides You Can Use

Published on Aug 26, 2024 in writing by Nicolas Bohorquez
8 minute read

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 userbase. Consistency also 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 your business produces, and all of your writers can follow it. 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 have made their own technical writing style guides available publicly so you can analyze their strengths as you create your own style.

Draft.dev Style Guide

The 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: This section 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

The style guide from A List Apart 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. It also suggests following The Chicago Manual of Style and Fowler’s Dictionary of Modern English Usage as principal references for proper language usage.

DigitalOcean

DigitalOcean’s Technical Writing Guidelines contains detailed information about how to write compelling technical articles for its 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 (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 the desired structure for its 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 using 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.

DigitalOcean’s 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 with roots dating back to 1871, provides a concise guide covering many important aspects of technical writing. Its first section provides ten 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 paragraph 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 like 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 Merriam-Webster’s Collegiate Dictionary and The Chicago Manual of Style.

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. It also includes tips on writing for an international audience, something that’s especially important to consider in technical writing:

“Following international style helps readers with limited English proficiency read what you write. By following international style, you also help translators—human or machine—localize your writing by minimizing the burdens of cultural and customary language usage.”

GitLab Documentation Style Guide

GitLab uses the same guide for 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 its team handbook, which defines a list of rules covering a variety of topics, including the use of ubiquitous language 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 here are a few highlights:

• 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 documentation guides for application programming interfaces (APIs).
• 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 file names, domains, trademarks, and more.

Microsoft Writing Style Guide

Many other sources reference the Microsoft Writing 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) and its sections on content and design planning, scannable content, and selecting 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. It covers scenarios that range from creating a scripted chatbot to writing responsive content for the web. 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 as 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.

Build a Blog that Software Developers Will Read

The Technical Content Manager’s Playbook is a collection of resources you can use to manage a high-quality, technical blog:

• A template for creating content briefs
• An Airtable publishing calendar
• A technical blogging style guide

Download Now!