IN THIS ARTICLE

    Styleguides

    The best-in-class technical writing styeguide examples (and why they work)

    User guides. Proposals. Reports. Technical documentation. Case studies. A technical writer has to wear many hats to get the job done.

    At a basic level, technical writing involves communicating complex information so readers can use a product — even if they aren’t an expert. This approach can be applied across many sectors, like high-tech manufacturing, biotech, engineering, finance, and computer technology.

    Making all of that complex information cohesive would be almost impossible if it weren’t for two things: assignment templates and the styleguide. Here’s what you should know about styleguides when it comes to technical writers:

    What is a styleguide in technical writing?

    In general, the point of a styleguide is to provide consistency, whether you’re writing an article or a social media post. It typically covers the basics, like:

     

    • Punctuation (guidance on how to use things like hyphens, parenthesis, semicolons, and the Oxford comma)
    • Grammar (rules for things like capitalization, parts of speech like conjunctions, , and prepositions)
    • Tone 

     

    For technical writers, a styleguide can also cover things like product description guidelines, report structuring, linking best-practices, and when to use abbreviations or acronyms. This provides a solid foundation for templated content. So it’s especially useful for technical writers who may be working on the same type of assignment regularly.

    For those interested in diving further into the topic of editorial styleguidelines, resources like The Elements of Style, or a stylebook like AP Style or the Chicago Manual of Style, can provide valuable insight. It’s also a good idea to familiarize yourself with those stylebooks because many styleguides use them as a baseline, offering guidance where they diverge from the rules.

    What are the five types of technical writing?

    In addition to traditional technical writing (content produced with a technical audience in mind, like appliance repair manuals and programmer guides), there are five umbrellas assignments tend to fall under:

     

    Technological marketing content: Technical writing that’s tied to advertising, product promotion, and marketing.

    Examples:

    End-user documentation: Technical writing presented as how-to information for electronics and other consumer products.

    Examples:

    Field service support: Technical writing intended to aid in technical work and often requires the writer to develop and analyze procedures and documentation for various types of work (for example, equipment and software installation, maintenance, and administration.)

    Examples:

    Developmental support: This kind of technical writing requires you to analyze information and work with experts on the topic to create functional and technical specification documents or systems analysis documents.

    Examples:

    Organizational support: Here, technical writers would identify process and project objectives and limitations (think: stakeholders and critical success factors) and help define deliverables.

    Examples:

    Document styleguide examples for technical writers

    Best technical styleguide for navigation: Google Developer styleguide

    As any technical writer knows, when you have a lot of information to present, organization is key. The Google Developer styleguide solves the organization problem by keeping the reader in mind throughout. It begins with an introduction section that covers the basics — goals of the guide and how to use it — and then breaks things down into a more digestible format in the Highlights section. That covers other high-level topics, like:

     

    • Tone and content (including accessibility)
    • Language and grammar (like using active voice vs. passive voice)
    • Formatting, punctuation, and organization
    • Images

     

    Those sections have linked key takeaways, so the reader can get the gist of things and access more in-depth information with a single click. That’s vital when you have a guide (and sidebar) as lengthy as Google’s developer guide.

    The sidebar also divides things up in a way that is both intuitive and easy to read, with bolded headers. And the search function at the top of the screen makes it even easier for readers to find what they need. Together, these factors make the guide less intimidating, even if you’re a first-time visitor. That’s key for a growing company.

    Best example-based technical styleguide: Microsoft’s styleguide

    Guidelines are good. Concrete examples are better. And the Microsoft writing styleguide is packed with useful examples, including both what works and what doesn’t for its rules.

    For instance, in the Bias-free communication section, there are tables labeled with headers like Use this and Not this. This direct comparison makes it easy for a reader to grasp the information at a glance. And the table itself also provides a break from the more traditional text format, adding another layer of digestibility.

    Not every page of this styleguide goes into this level of depth (and it isn’t always necessary to do so). But it makes a difference when they do because example-based pages are allocated to more complex sections, like pages that fall under the Grammar umbrella. This, and peppering in context like exceptions to rules, gives a complete picture of what’s expected while anticipating reader questions.

    Best one-page technical styleguide: IBM’s styleguide

    While the other styleguides listed here rely on housing information on separate pages, the IBM styleguide keeps everything on one page. In the wrong hands, that could be a recipe for reader confusion and overwhelm. But this guide avoids the potential pitfalls of this structure through two key tools:

     

    • Visual organization (like headers, bolded takeaways, bullet points, charts and color-coding)
    • Jumplinks (both in-line and within the table of contents in the sidebar)

     

    Again, this styleguide keeps the reader in mind, offering information in a way that works for those who are reading the content start to finish (like a new employee would), as well as for those who are skimming for the information they need and may be under a deadline. So instead of presenting as a wall of text, it’s broken down into the most crucial bits of information.

    And beyond that, the information is written using the writing style and guidelines it puts forth. For example, the guide provides an educational example for writing conversationally: “And another thing. You can start sentences with “And” or “But.”” This meets that conversational standard, but it’s also active and to the point. Bottom line: Leading by example is one of the best ways to get readers to understand, and use, your guide.

    Best streamlined technical styleguide: Apple’s styleguide

    A good styleguide provides enough information to make readers understand what’s needed without bogging them down in a sea of excess. In the case of the Apple styleguide, that means slimming down the content as well as the menu.

    Unlike the other guides on this list, Apple hides the more in-depth information in drop-downs within the menu, creating a more simplistic view of the information. When you click into the sections, most of those also offer an Overview page which can answer more common questions, like basics of international style or writing units of measure. Then subsequent pages go deeper, addressing specifics, like including ISO standard context and prefixes for units of measure.

    Another key to this guide’s success is the strategic placement of the updates page, located under the About the guide section. That makes it easier for returning visitors to stay updated about changes in brand style. That’s vital for any business, but especially if you’re building a styleguide from scratch, when larger changes are more likely.Creating a styleguide is a big undertaking, though. And while you can, and should, take inspiration from the above examples, it will still require a significant amount of work to make a guide that meets your company’s needs. For that, Writer’s styleguide tool can help.