Style Guides in Technical Writing: Why and How to Use Them
You may have heard that a style guide is a useful tool in technical writing. But what exactly is a style guide, and why is it so useful?
What is a style guide?
A style guide is a collection of guidelines that help maintain a consistent style throughout the content you produce, especially when it is written by more than one person.
There are many kinds of style guide. For example:
a brand style guide (such as the Firefox style guide) covers things that affect an organization’s branding, such as logo usage, font, colours, and imagery.
an academic style guide (such as APA Style from the American Psychological Association) provides guidelines on writing academic papers, including things like citing sources and references.
an editorial style guide (such as the SFU Editorial style guide) covers things like spelling, grammar, punctuation, and word usage.
A style guide meant for technical writing will, like an editorial style guide, contain general guidelines for things like spelling, grammar, word usage, and formatting, but it will also contain specialized guidelines for creating various types of technical content for an organization.
For example, this page describes Microsoft’s approach to describing interactions with a user interface.
Source: Microsoft Style Guide
Why use a style guide in technical writing?
A style guide can make things easier for everyone involved in technical communication:
Writers can quickly look up guidelines and examples to keep their writing consistent with their organization’s style and with other writers who are producing content for the same product or organization.
Technical editors (who are often responsible for maintaining style guides) can direct writers to the style guide to save time and reduce disagreements during the editing process.
Users won’t be confused by multiple heading types, different spellings, inconsistent formatting, or multiple terms for the same thing. Consistency makes content easier to read, navigate, and understand.
Organizations will benefit from having content that looks more professional and authoritative and is easier for users and customers to read and understand.
How to use a style guide in technical writing
Here are some tips on writing technical content while using a style guide.
Check the style guide before you start writing to remind yourself of general principles (such as avoiding jargon or using inclusive language).
Consult the style guide when setting up the headers and structure of your document. Many organizations have document templates that limit the need for this type of setup work.
While writing, check the guide whenever you need to make a usage or formatting decision (for example, formatting a bulleted list, or choosing between a list or a table).
After writing your first draft, check your work against the style guide to make sure you’ve followed formatting, spelling, grammar, and content guidelines.
Choosing a style guide for your technical content
There are several approaches you can take to choosing a style guide:
Look at existing technical style guides such as the Google developer documentation style guide or the Microsoft Style Guide to help decide what is right for your organization.
Maintaining and using a style guide requires effort, but by providing guidelines for consistency it ultimately makes the technical documentation process easier and makes content easier to read, navigate, and understand.