FAQ on Technical Writing
In my article called ?Cons of a Technical Writing Job?, I mentioned that technical writers should follow style guidelines and standards because technical documentation should be concise and grammatically correct. But novices may ask, what styles guides should they follow? To answer that question, I?ve created a list that you?ll find below.
First of all, let?s figure out what a style guide is. A style guide is a set of standards for writing and designing content; it defines the style that should be used in communication within a particular organization. If you have a background in journalism, for example, you might have read the Chicago manual of style. This style guide provides general information about grammar and syntax. But this alone is not enough for writing technical documentation.
In order to write documentation in a more clear way and keep a consistent tone, voice, and style in your documentation, read and follow one of these style guides:
- A list apart style guide
A List Apart explores the design, development, and meaning of web content, with a special focus on web standards and best practices.
- Techprose techwriting guidelines
TechProse is a technical writing, training, and information technology consulting company in business since 1982. This manual provides technical writing guidance and sets standards for creating logical and professionally written material. TechProse provides it to staff writers, consultants, and students studying Technical Writing with a TechProse staff member.
- Microsoft manual of style
Maximize the impact and precision of your message! Now in its fourth edition, the Microsoft Manual of Style provides essential guidance to content creators, journalists, technical writers, editors, and everyone else who writes about computer technology. Directly from the Editorial Style Board at Microsoft ? you get a comprehensive glossary of both general technology terms and those specific to Microsoft; clear, concise usage and style guidelines with helpful examples and alternatives; guidance on grammar, tone, and voice; and best practices for writing content for the web, optimizing for accessibility, and communicating to a worldwide audience. Fully updated and optimized for ease of use, the Microsoft Manual of Style is designed to help you communicate clearly, consistently, and accurately about technical topics ? across a range of audiences and media.
- Oxford manual of style
The Oxford University Style Guide aims to provide a guide to writing and formatting documents written by staff on behalf of the University (or one of its constituent departments etc). It is part of the University?s branding toolkit which enables the University?s formal documentation to be presented consistently across all communications.
- IBM style guide
Each topic addresses the most common situations and gives examples where appropriate. With some exceptions, developerWorks style is based on the IBM style, which is defined in The IBM Style Guide: Conventions for Writers and Editors. Sidebars indicate the relevant sections in the IBM Style Guide. Refer to the IBM guide for more examples and cases not documented in this developerWorks guide. Most of the conventions and style guidelines outlined here are standard practices and have been in place since the inception of the developerWorks website. However, like any effective editorial style, developerWorks style evolves to adapt to shifts in how readers consume content. Consider the following ideas for modernizing article style as you apply the standards and guidelines.
- Handbook of Technical Writing
From formal reports and manuals to everyday e-mails, The Handbook of Technical Writing uses smart, accessible language to spotlight and clarify technical writing today. Hundreds of topic entries, 90+ sample documents, at-a-glance checklists, and dynamic videos break down the best-practices, models, and real-world skills that successful writers use to clearly and persuasively communicate technical information and data.
Developed by a legendary author team with decades of combined academic and professional experience, the book?s intuitive, the alphabetical organization makes it easy to navigate its extensive coverage of grammar, usage, and style. Plus, updated, in-depth treatment of pressing issues like the job search, the writing process, documenting sources, and social media resonates both in class and on the job.
- A11Y Style Guide
The A11Y style guide comes with pre-populated accessible components that include helpful links to related tools, articles, and WCAG guidelines to make your site more inclusive. These components also serve as a guide for both HTML markup and SCSS/CSS code, to inform designers, front-end and back-end developers at every stage of the website?s creation.
- Open SUSE Style Guide
This guide provides answers to writing, style, and layout questions commonly arising when editing SUSE documentation. The GeekoDoc/DocBook markup reference at the end of this guide will help you choose the right XML element for your purpose. Following this guide will make your documentation more understandable and easier to translate.
Conclusion
Some writers find the following style guides restrictive because they prefer to have a freer hand in grammatical constructions, for example. But you definitely should read and follow them because style guides make your documentation more effective and easy-to-interpret.
What styles guide do you follow? What issues did it help you solve?
How did I become a technical writer? What skills do you need? Read FAQ on Technical Writing.
