Using a Style Guide for Technical Writing to Improve the Quality of Your Content
Law & Legislation
To improve the quality of the user manuals, online help et cetera that we create for our clients, we recently created our own style guide. This guide is inspired by some existing style guides.
Time to take a closer look on style guides in general.
In this episode I talk with Scott DeLoach and Mike Unwalla about Using Style Guides in Technical Communication.
Listen to this episode if you want to gain more insight on how to apply existing style guides or create your own to improve the quality of your ‘information for use’.
Table of Contents
Hi, there, and welcome to the show. In this podcast, we're going to talk about using style guides in technical communication.
A style guide is a set of standards for writing and designing contents. A style guide for technical writing defines the style that should be used in technical communication, such as in user manuals, online help, and procedural writing.
A style guide helps you to write documentation in a clearer way, and to keep a consistent tone of voice and style.
To improve the quality of the content that we create for our clients, we recently created our own style guide. This guide is inspired by some of the existing style guides.
During my research, I came across many different style guides that I will list here, so they show up in the transcriptions of this episode, including links to where to find them. Many of them are freely available.
These style guides include:
- The ASD-STE100 Standard, or the Simplified Technical English style guide
- The Microsoft Manual of Style
- The Chicago Manual of Style
- The Oxford Manual of Style
- The Handbook of Technical Writing
- The Apple Style Guides
- The IBM Style Guides
- The SAP Style Guides
- The Google Style Guides
- Kohl's Global English Style Guide 2008
- Shipley Associates Style Guide for Oil and Gas Professionals
- The Department of Defense Writing Style Guide and Preferred Usage
- The Style Guide for the Atlassian Developer Documentation
- Tech Pros
- SAE International Technical Paper Style Guides
- A List Apart Style Guides
- The Red Hat Style Guides
- Economist style guide
- The GNOME Style Guides
- Read Me First!: A Style Guide for the Computer Industry
And the following open source style guides:
- The 18F Content Guides
- The openSUSE Style Guides, and
With this episode, I hope to provide more insight on how to apply existing style guides or create your own to improve the quality of your information for use.
In this podcast, we will discuss:
- The difference between a brand style guide and a technical writing style guide
- Some of the style guides that are available and when to use them
- How a style guide can help you to write better documentation, and
- How to create your own style guides.
Let me introduce today's guests. Our first guest today is Mike Unwalla. He's from Sheffield, South Yorkshire in the United Kingdom. Mike is a freelance technical writer and helps organizations to make their technical documents as clear as possible through his website, techscribe.co.uk. He discusses all kinds of topics related to technical writing, such as language, design, standards, and document production.
Mike specializes in simplified technical English, language quality assurance, technical editing, and text simplification. He has built a term checker for ASD Simplified Technical English.
Our second guest is Scott DeLoach. He's from Miami Beach, Florida. Scott is founder at ClickStart. Scott specializes in UX/UA, so, user experience and user assistance, policy and procedure consulting, and HTML5 CSS training and consulting.
He has 25 years of experience designing and developing user interfaces and user assistance. He's the author of the MadCap Flare Training Guides and MadCap Flare 2020: The Definitive Guides.
Mike: Hi, Ferry.
Ferry: Two questions to kick off. Mike, UK English or US English?
Mike: Whatever the customer wants.
Ferry: Scott, hardware documentation or software documentation?
Scott: Most of my work is with software documentation, but I enjoy both of them.
Ferry: All right. Thanks. So, we're going to talk about style guides, and specifically style guides that you can use in technical documentation, technical communication. Why is a brand style guide or style guide such as the Chicago Manual of Style not sufficient for technical writers?
Scott: I can think of a couple of reasons for that. If we think about, say, a brand, I would call it more of a brand guidelines document. It usually comes from the marketing department, and it's primarily focused on colors, fonts, logos that you're supposed to use and when you're supposed to use them.
So, all the branding elements, but they rarely talk much about word usage as much or things that come up in our technical documents.
As for the Chicago Manual of Style, it's almost the opposite, but it's a little generic. So, it's more how to use contractions or when to use an acronym, but it's not necessarily focused on exactly what we're doing.
So, I think they both support what we want to do. There's components of it. But if you only have a brand guidelines document or you only have the Chicago Manual of Style, you're missing a lot of useful information that you're going to need to document.
Ferry: Yeah. Thanks, Scott. So, why do you think you need a style guide in technical communication? What are the advantages of using style guides?
I think all three of us can come up with numerous advantages. I'll just pick one. I don't want to monopolize it. To me, the biggest advantage of a style guide, and the way that I use it the most often, is I really like to have examples, because I might forget a detail. Even something that people argue about all the time, "Are we going to have a period at the end of items in a bulleted list?" Even something like that, I can see a quick example and realize, "All right, we do use periods," or, "We don't use periods," or how to format a table. Same thing, an example.
If there's something I can quickly refer to and see how I'm supposed to do it, or if it's formatting, quickly copy and then use it for what I'm writing. That's an incredible time-saver and it makes sure that everybody's consistent.
Yeah. I agree strongly with Scott. If we have some kind of reference to go to there is no argument. And, Scott was talking earlier on about terminology and I've worked with... Well one company that I'm thinking of they had 13 different terms for the same item. And, I have heard of organizations who have had up to 40 terms for the same thing. With a style guide when you have one preferred term and you know where you stand, it's asking a lot of customers to understand 40 different terms for the same thing. It just causes so much confusion.
So, it improves communication by ensuring consistency.
LanguageTool: https://www.languagetool.org/ (scroll down to get the 'Desktop version for offline use', which is customizable)
Vale Server: https://errata.ai/vale-server/ (it's commercial, not free)
Other style guides:
Economist style guide: https://ukshop.economist.com/p
Read Me First!: A Style Guide for the Computer Industry https://www.amazon.com/Read-Me
Edmond H. Weiss, 2005. The Elements of International English Style: a guide to writing correspondence, reports, technical documents, and Internet pages for a global audience. New York, M. E. Sharp. 162 pages including appendices. ISBN 0-7656-1752-X.
Chris Bar and the senior editors of Yahoo!, 2010. The Yahoo! Style Guide. London, Macmillan. 512 pages. ISBN 978-0-230-74960-3.