Using a Style Guide for Technical Writing to Improve the Quality of Your Content

ASD-STE100 and the Global English Style Guide

Ferry: And, Mike what style guides do you have experience with?

Mike: The two that I know very well are the Global English Style Guide by John Kohl and the ASD-STE100 specification. Which, I mean, I have to stress, it's not a style guide and it doesn't position itself in the market as a style guide.

But, it has many similarities to a style guide, especially in terms of the terminology recommendations.

Ferry: Yeah. Because the ASD-STE, so the Simplified Technical English specification, is quite clear in as really clear rules. And, I think they are one of the few style guides, if we call it a style guide, that also calls it a rule where other style guides are a bit more.... They describe the rules in a certain way. Do you know what I mean?

Mike: I mean, that's why I like the Kohl style guide because it is a set of rules or perhaps best practice guidelines. But, they are all developed from data. They're not opinion. They have a solid foundation in validated data. We've done these tests and we've done those tests and thus we suggest you use this guideline.

Ferry: Can you tell us a bit more about this? Well, let's start with the Simplified Technical English specification. What is Simplified Technical English?

Mike: Simplified Technical English is a specification for a controlled language. So, what's a controlled language?

A controlled language is a natural language such as English or French or Chinese that has restrictions on the vocabulary and on the grammatical structures that you can use.

Typically that's done to make the text as easy as possible to read. Sometimes it can be done so that you can make texts that are computationally analyzable. The STE specification is designed to make texts easy to read.

And it was only started off 40, 50 years ago in the aerospace industry where a lot of the technicians did not use English as a first language.

And so the players in the industry got together and developed some guidelines, which turned into the ASD-STE100 specification.

Now all the specification, various ballparking, 3% of the terminology is specific to the aircraft industry.

The specification now is applicable to all types of special safety, critical domains, where you need to make sure that your text and particularly your instructional text is unambiguous and as simple to read as possible.

The Free-To-Use Online STE Dictionary that we created at INSTRKTIV

Ferry: So it's more hardware oriented than it's software.

Mike: It can be used for both, and it's started off as more hardware oriented, but it certainly got sections now for IT, and computing terminology.

It doesn't exclude that and I've used it in my software documentation projects. And I think it's applicable already to all types of instructional material, where you want to be as clear as possible.

It's not useful for marketing documentation, it's not useful if you want to have, well, just say-

Ferry: How can you achieve being as clear as possible, or how can you achieve that according to the STE specification?

Mike: I'll start with easy parts. So the terminology management, terminology.

So in English, we have many synonyms for the word large. Big is a typical synonym and there are many others but you probably wouldn't find them so much in technical documentation, such as huge or enormous.

The STE specifications that we're going to use, we're going to define the word large is the approved term where you're making some kind of comparison. That's the adjective we're going to use. Don't use big, don't use huge. So that kind of relates it.

I think most technical writers will agree that we have one term, one meaning, one technical term.

What has one meaning?

So you don't call it a gizmo and a widget and a doofer when they all refer to the same thing.

Now, if you accept that principle for technical terms, there's no reason not to accept that principle for non-technical terms that you can find in a standard dictionary. So that's one part of the terminology.

The other part is the technical terms and that there are rules in STE that say, choose a term and use it consistently.

On the grammar side of things, the specification restricts the tenses that you can use. So it doesn't permit me to write something like the past or the past perfect tense after something has been done. I have to say, “after it was done,” just a simple past in the passive voice.

But one of the reasons for that is that the tenses in English are not the same as the tenses in other languages. And some languages don't have equivalence to the tenses that we have similarly.

Some languages have tenses that we don't have. For example, Turkish has a suffix that sounds like 'mish'. [Editor's note. The suffix is '-mİş'. Refer to https://elon.io/learn-turkish/lesson/the-evidential-past-suffix-mi%C5%9F.]

In Turkish, they might say, "O gülmiş", but we might say, “It's reported that he or she laughed.”

Sample page with STE writing rules

Ferry: Right. And are these... You're being very specific now about the tenses. Is that something that you see in the Kohl style guide as well, or is this very STE specific?

Mike: Kohl comes from a different perspective. So STE takes this perspective. If it's not approved, you can't use it. Kohl says, if there are no problems with it, you can use it. I can't remember what Kohl says about tenses, but let me just look him up in my style and see what he does say.

Ferry: Does this sound familiar to you, Scott? So what style guides are you familiar with?

The Microsoft and Google Style Guide

Scott: I use quite a few since most of my projects are software based. I'll use things like the Microsoft Style Guide. A lot of times I have to deal with mobile devices. Joe Welinkse has a great book about writing for mobile devices.

It's not really a style guide, but it has a lot of style examples and advice. So it can be used at least as a style guide unless you have a specific one, it's called Developing User Assistance for Mobile Apps. So that's a good reference for me.

The other one I use very often is Google's. Google's Developer Documentation Style Guide. And that's because a name you mentioned you had a fantastic list at the beginning when you're starting out, if you can say, "Hey this is based on Google's Style Guide, or IBM Style Guide, or Microsoft Style."

That gives a lot of weight to it.

So it ends a lot of those arguments about say, "Hey, they're a giant company this is what they do. If we do what they're doing, it will probably be okay."

Ferry: So would you also prefer to choose a style guide that you're going to apply for a certain project or for a certain client? Or can it be a combination of several style guides?

Scott: I think it depends on the client.

For example, if they're focus is, "Hey, this is going to be used almost exclusively on a mobile device." I'm going to start with one that focuses on mobile style guide information."

If they're doing a little bit broader... I've seen groups literally pick and choose, open up what each one says about something and say, "All right, we agree with that. Let's copy that, put it in our style guide." So sometimes people do that. It really depends on the group. Yeah.

Ferry: Yeah, exactly. We're going to talk about how you can create your own style guide later, I hope. Mike, when you've found what you're looking for, you'll let me know.

Mike:  Okay. Well, I've got some examples here. Rule 3(4), keep phrasal verbs together. So on page 38 because I can never remember. I need to find an example.

Ferry: And this is how you actually use the style guide, right guys, so you're constantly consulting it and seeing where, what the rule is, looking for examples.

Scott: Exactly. This is like a perfect live example of using one.

Mike: Well, and Scott's going to talk about, I believe, automation, aren't you Scott? Because that's so important and how much time do we waste looking in a document, where-

Scott: Oh, for sure.

Mike: ... software can do it for us. But okay, so here we are, 3(4), keep phrasal verbs together. It's got priority levels.

So for human translators and non-native speakers, it's not so important. For machine translation, it's VERY important. So where possible, keep the parts of a phrasal verb together.

Turn the zoom tool off, by clicking the circle tool or turn off the zoom tool, by clicking the circle tool.

And then, it just doesn't say that but it gives reasons. So separated phrasal verbs confuse some non-native speakers, who don't know those verbs.

It helps with consistency because if you write somewhere 'turn' then a noun phrase and then 'off' and elsewhere, you write 'turn off' and then a noun phrase, well, there's an inconsistency.

From a stylistic perspective, Kohl suggested, 'turn off the zoom tool' is nicer than, 'turn the zoom tool off'. And the last point, is this better for machine translation?

Ferry: Is this something like parallel constructions or is that something different?

Mike: Parallel constructions is something different but it could be ... I mean, if you had a set of instructions with phrasal verbs in and you kept the phrasal verb ... You kept the particle ... You separated the particle from the verb with the noun cluster and elsewhere, you didn't, then indeed, you wouldn't be obeying the rule for parallel constructions.

Ferry: I'd love to bring in some examples, that makes it much more alive. So if you guys have any examples that explain some rules of the standards, please bring them in.

Mike: Yes. Okay. How about this one from German then?

So I was talking earlier on about the STE restricts, the tenses that you can use, Kohl rule 3(5), use short, simple verb phrases.

So it's saying, in other languages, verb tenses are not always linked to time and different languages use different tenses to express the same point or range on the time access.

For example, in English, we use present perfect progressive, have been living, to express what a German conveys using the simple present 'wohnen'.

English: I have been living in Berlin for 12 years.

German: Ich wohne seit 12 Jahre in Berlin.

Ferry: By the way, guys, the Kohl style guide and the ASD-STE100 style guide and those, the Microsoft and the Google style guides, aren't these freely available or do you have to purchase them?

Mike: They are freely available and you have to purchase them. And yes, I mean, they're easy to get. ASD and Microsoft's writing style guide are free. Kohl, you have to pay for. I think it's approximately €30, perhaps a little less.

Ferry: What do you know, Scott, about the Google Style Guides?

Scott: Google Style Guide is on their website and the Microsoft Style Guide, which started out as a book, the Microsoft Manual of Style but that has been replaced by the Microsoft Style Guide.

Microsoft and Google, both on their website, freely available and they often update it.

Both of them have kind of a feedback section too, so if you want them to add something or you disagree with something, it's available.

Mike: Well, I'd like to kick in there and say, yes and that's a HUGE disadvantage over a book or something like ASD, which is revised once, usually every three years because you just don't know that something's changed.

Ferry: Exactly. And then I think it was reversed in 2017, the latest version of the ASD-

Mike: That's right.

Ferry: ... STE, is that correct?

Mike: Yeah. The next one will be next year.

Ferry: Because the ASD standard consists of two parts, so it's a dictionary and it's a set of writing rules. And as far as I remember, for example, with such an update, whilst some words are added to the dictionary, is that correct?

Page from the STE Dictionary

Mike: That's right. And the writing rules were simplified and changed also. It's not just dictionary maintenance.

Ferry: Simplify it, so it gets easier.

Mike: Yes. I mean, the rules, some of the rules were quite ... Some of the grammar rules were quite confusing and seemed to conflict. So they rewrote a lot of those, to make the rules clearer.

And of course, certainly vocabulary always changes and so, they continually update the terminology that's not approved and the suggestions for unapproved terms.

One of the things I think they don't do very well, is to explain that a lot of the dictionary is about word sense disambiguation. So it's not that a word or for example, a verb is not approved.

It's not approved with a particular meaning but if you can use it, if you have a ... If it's your technical term, then you want to use it.

So what you need to do is, is to use it in its correct technical context and make sure that you don't use it in it's incorrect context. And I'm just going to ... Talk amongst yourselves for a moment, I'm just going to find an example.

Ferry: Yeah. Of a noun or a verb, you mean?

Mike: Let me find one.

Ferry: Is that something that is being discussed in the Microsoft manual, Scott? Does the Microsoft and Google manual contain a list of or a dictionary of approved and non-approved words?

Scott: Yes. I have both of them open. So they have different sections. The Microsoft Guide, for example, has sort of a table of contents and very near the top, it has A to Z word list and terms.

So the words are scattered throughout, there is a section on tone, there's a section on capitalization.

So words will come up but they do have them combined, both of them have them combined in a section. And they both have a search as well, so you could just search for how to do something.

Ferry: Let's do a bit of a search. For example, it confuses me all the time when to use click and when to use select.

Scott: Okay, you got it. All right.

So the word CLICK. This is from Microsoft. It says avoid this verb, which is specific to using a mouse. Instead use verbs that work with multiple devices, such as select.

It's okay to use CLICK when you need to describe mouse actions specifically. So I think that's very good advice.

We were talking about updating. One of the things that Microsoft is probably the best out of the examples I've seen.

Not only do they tell you when the last time it was... so this one, as an example, was updated last January, 19th, 2018. They even tell you who on their team contributed to it.

And you can even contact them if you want to. So it's very tied to the authors and to the last date it was updated.

Ferry: You've opened it online. So you don't have a print copy there.

Scott:You can download a PDF if you want to, but I think it's much better to use it online.

Ferry: It fits the type of company as well. Right?

Mike: Okay. I'll go. I've got an example here now from STE.

So the verb induce is not permitted if you mean cause. For example, scratches in the windscreen may induce cracking. So this STE says, "Don't use induce. Say scratches in the wind screen can cause cracks," but induce can be a technical verb as in inducing a current in a piece of wire. So if you're in the context of electromagnetism, then it's fine to use the verb induce.

In STE oil is not approved as a verb, but is can be used as a noun (technical name)

Ferry: Okay. Meanwhile, I was checking, I found another example. So one that I have to use quite often, that's the word screw. So the word screw as a verb. So to screw something in is not allowed in simplified technical English. So only if the objects screw as a technical noun is allowed. So two examples are, so you can use, for example, screw in the following sentences. Continue... No, sorry. "Attach the straps to the panels with screws," and not allowed, "This screw straps to the panels." And so the standard clearly indicates which version is allowed and which version is not allowed. Is that correct?

Mike: Yes it is very. And it's interesting, it's not just the STE style guide that has rules similar to this. I can't give you the name of the company, but I was working, some years ago, working as a subcontractor on a shipping project and the company there used a style guide, which said, and he gave some examples of words that could be used as nouns, but not as verbs.

Scott: It seems like it definitely makes sense. It's kind of nominalization using a noun as a verb. It seems clear even to say connect using what you're going to connect it with or whatever the action verb is rather than using screw or nail or whatever the connection device is. It seems like better writing in general, plus I'm sure it's confusing for translation. It's just bad all around.

Ferry: Yeah. And then Scott, so I'm familiar with the Flare training guides, the guides that you've written. Did you use any style guide for them, because I know that they're very concise? They're very well, all information types are formatted and written in the same way. What did you use for those training manuals?

Scott: So I think that's a good example. We're talking about consistency. To me, that's the biggest thing that you get out of the style guide is consistency even if you're the only person writing, it still is very useful. So with a tool like Flare, the way that it's set up is you can have a global project.

So we have several training guides and they are their own projects. You could think of the equivalent of say separate Microsoft Word documents, but you have this global project. And that's where I keep all of my examples.

So I have an example table, I have an example bulleted list, a numbered list, paragraph, even small kinds of boiler plate topics.

And I follow the style guide rules in the samples. So, you use an example of a cross-reference, I have a sample cross-reference.

So if I forget how I'm supposed to format one or set one up, or I'm worried that I did it wrong, I know I can go to that global project and copy it. The way that Flare works is you can import from a global project into a child project.

So it's even more convenient because I have it right there and the child project. If I need something like we were just looking things up, I don't have to go anywhere to look for it.

It's right there. It's in the project. I go there. It's right there. I copy it and paste it in. It takes maybe a minute.

Ferry: So that’s your database of reusable content already, actually based on principles you took from style guides.

Scott: Exactly!

Ferry: Yeah. That's a good way of working. You were talking about, you have experience with the Microsoft manual of style and the Google manual of style. What are the main differences between those two?

Scott: One thing that I think we were talking about maybe copying and pasting or making your own style guide, one big thing that you need to keep in mind, and they're very clear about this.

In fact, the first topic in the Microsoft style guide, since that's the one I still have open, the first topic is about Microsoft's brand voice. So they make it very clear, "This is our style guide and it follows our brand and how we do things. It may not match how your company does things."

Mike was talking about how a lot of these concepts are based on research. So there are things that are facts that it's hard to have a different opinion about people who've done a lot of research.

This is what works. This is the right way to do something. And those are in here, but there are many things where there's, "Well, you could do it this way. You could do it this way." There's no definite right or wrong.

So Microsoft tells you up front, and Google does the same, "This is how we do it. So we chose because that matches our brand. That may not be the best choice for you." And they both do a good job of presenting options. Microsoft has a section when they talk about tone, and they give examples.

And they even say, "Hey, in this situation, this might work best. In this situation, this could work best." And Google does the same thing.

I think when you make your own style guide, and many of those places you can pick because you know your brand. You can say, "No, this is how we do it. We don't have two ways to do this.

We do it this way. So do it that way." So, those are the differences that you see based on their own branding capitalization. They capitalize things a little bit differently, so there are small differences.

Using Capitilization in Styleguides

Ferry: That also can be quite challenging to choose how to capitalize certain words. For example, headings. What do the style guides say that you have to have right now? So at Microsoft, Google, or STE, for example, do you use all caps or initial caps?

Scott: That's one that's interesting about Google. Google's branding, their tone, is less formal, I would say, than maybe some other companies.

Google just uses initial caps. I'm looking at a particular section right now in the style guide: Writing accessible documentation.

Only the W is capitalized, whereas even a company like Microsoft would typically capitalize... They would do initial caps all the way or title cap. They would capitalize the W, the A, and the D.

So, I see that varying a lot between companies, how you capitalize headings. We all have a preference. My preference is just capitalizing the W and this is an example, but that's only a preference. That's not based on facts.

Capitization rules of the INSTKTIV Manual of Style

Ferry: Right. And Mike, if you want to interrupt me, go ahead.

Mike: Yeah, well, STE says... one of the headings in the preface does STE regulate text formatting. No, it doesn't tell you how to write your headings and that's for your style guide to specify.

Ferry: Doesn't STE say anything about capitalization?

Mike: I don't think so. It might, I mean, STE assumes that you are writing correct English. So if you need a capital at the start of the sentence, STE doesn't tell you to do that. I'm not sure what it says about lists. It might tell you to start a list item with a capital letter but I'm not sure.

STE requires to start each item in a vertical list with an uppercase letter

Style Guides About Writing Procedures for Mobile and Desktop

Ferry: And meanwhile, so a big chunk of writing technical documentation or technical content is writing procedures and instructions.

What do you think, how does a good procedure, a sequence of steps, for example, look like? First of all, what do you think it should look like? And what do the style guides say that you're familiar with?

Scott: That's maybe one of the most interesting places where things seem to differ. If you look at a style guide that focuses on writing for mobile devices, I mentioned Joe's book, he talks quite a bit about that specific situation.

So, writing for a mobile device, the steps are extremely minimal. I follow minimalist writing principles all the time. And even to me, it seems extremely minimalist.

There are very few words writing a step for a mobile device, specifically for a mobile device. And even when I bring it up in presentations or I'm teaching about it, I even try to prepare people because if you haven't seen it it's almost jarring how little is there.

So that's different. Even what is often called a feedback statement, where you have a step and then a paragraph that's sort of explaining the step and then the next step.

Even those feedback statements are often excluded when you're writing for a mobile device, because they just take up space, so they are left out. That's a place where you see a lot of differences.

Ferry: And do you have two examples? For example, of an instruction that you would use in online help, for example, for desktop purposes and a sentence that you would use for mobile documentation?

Scott: I can make up an example off the top of my head. So, something like Click print, and then there might be a sentence after it: 'The document prints'. So there's some feedback that the document prints would absolutely be left out for mobile.

Mike: Well, I want to question that. If the feedback is necessary and it's not in mobile, then there's something missing from the mobile. If it's not necessarily mobile, why would anyone want to put it on the desktop?

To me there's good writing and there's bad writing. And if an instruction requires a feedback step, feedback information, then it needs to be in there. And if it's not necessary, then putting it in there is bad writing.

Ferry: Right. But that's confirming that something's being printed is taking away uncertainties for the user or just confirming that he or she did something right.

Mike: Why is it necessary? If it's necessary, why isn't it in the mobile? And if it's not necessary in a mobile, what's so special... are the mobile users a bit more savvy than the average desktop users such that they don't need to be told that this document will be printed?

Ferry: Could be, but it may be a cultural thing as well that some cultures... I know that some cultures like to have more feedback on if they did things right.

Mike: Okay. But that's a different issue isn't it? Then that's cultural and it's... let's talk about one person from one culture one day using a mobile device and the next day using a desktop device, why are they different instructions?

Scott: I agree with what you're saying. As I was saying, I'm a minimalist, so you have to argue for me to add words rather than... It's harder to get me to add them than for me to take them out.

Example according to the principles of minimalism

To me, the split is right, which you're getting at. I think a lot of times, especially if you're writing for print, we think, "Oh, this would be nice to have." So, we put it in. It's useful. It's not required, but useful. So, it's often in there.

The need to have that you're mentioning, I think would be there in mobile. It needs to be there. It's always there, but that nice to have is the gray area where we look at it and say, "Well, that's not essential so we could take that out." That's the part I see disappearing.

Mike: I accept that fully, Scott. And I'm a minimalist. But all I'm saying is if you don't need it for mobile, why do you need it? It's nice to know, but it's not necessary, so remove it.

Scott: Sure. Yeah, I'm not disagreeing with you. I think what's happening is it's in there now, because people thought, "Oh, this is useful." And then there's an approach that, oh, we're taking this out, because of the mobile. But I would argue, like you're saying, I normally write that way to begin with and I wouldn't have necessarily had it in there.

But another interesting example that helps people see it, something you see a lot of times in a step, there's typically a few different ways to do it.

Like a keyboard shortcut, or a menu. And often we list those. I wouldn't say it's necessarily right or wrong, but you might see do this, or this, or this.

Mobile, you always pick one and you don't tell them every way they can do it. You only pick one of them. Whereas if we have more space, there's a value in telling people, "Hey, here's the keyboard shortcut. Here's what the icon looks like."

Mike: Again, I'm going to disagree with you, Scott, because all of that low level navigation doesn't need to be an instruction.

Stick all that information in an appendix, or on a front page quick tips, and let users learn the quick tips, and then they don't need to be told every time, because you look on the screen and you see what the keyboard shortcut is.

Scott: True. And I'm not saying this is how I would write it. This is what I'm seeing.

Mike: Okay, yeah.

Scott: Yeah. So, I typically see a step that has a lot of or statements. Do this, or this, or this, or this. And people think, "Oh, yeah, that's the right way to do it." But then when they go to mobile, it's like, "Oh, we can't do that."

And I think that's the first time maybe people have dealt with maybe we... First, you get them to take it out from mobile and then you'd get them to think, "Do we even need this? Maybe we can leave this out all the time."

But mobiles typically are the first time they think about ever taking it out.

Ferry: Hey. And, Scott, so if you were going to write instructions for both desktop and mobile, which style guides would you prefer to use?

Scott: I usually start with the book that I mentioned, Joe Welinkse's book. And then I would use... I like the Google style guide.

It matches more of the tone and style that I usually write towards. It's, like I said, a little less formal than other ones. So, I usually start with those two.

Ferry: And so the Google style guide clearly distinguishes mobile documentation and desktop documentation, or maybe even print and online.

Scott: They have a section about responsive content and that's where they talk a lot about mobile specific issues. They have some nice guidelines too.

So, they also have a section about scannable content, which applies just in general, it's all this idea of chunking and making it easy to follow things.

They talk about pole facing to make things stand out, keeping it short. It's general advice. I think mobile has just made it pop in people's heads.

Like we've been saying, we probably should have been doing this all the time, but now people are actually doing it. It makes it more visible to them.

Ferry: And with scannable content, you mean the way you can find information when you have it on your screen, for example?

Scott: Exactly, yeah.

Ferry: In what cases would you use the Microsoft manual of style, or is it just the style preference that you have?

Scott: I refer back to both of them. Some of them... I'll give you a good comparison.

The Google style guide is very easy to find. If you're looking for information about say punctuation or formatting, those are the main headings.

So, if I'm wondering, "Hey, we need some rules about colons." Very easy to find that in Google's.

A little bit harder to find that in Microsoft without the search. So, the way that the content is organized and presented is very different between the two of them.

The information once you get to it is very similar, but finding it is a little bit different, because of the way they organize it.

Ferry: Okay. We created our own internal style guide and I like to apply the rules and the use of Simplified Technical English, apply to the dictionary, but it's not always complete.

So, for example, and it may be different than in the 2017 update, maybe you can confirm it, Mike, but there was a lot of software terminology missing.

So, for example, click, select, enter versus type, et cetera.

So, it didn't provide an answer for all things that you can find on your path when writing documentation. And of course, some things you do simply because it's your way of working.

So, the way you write documentation and that may be different than described in the Simplified Technical English standard for example. So, it was a bit contradicting sometimes with the way I used to work and I thought, "Okay, I need my own style guide."

And that's why I researched existing style guides and finally decided to combine bits of the IBM style guide, the SAP style guide, Simplified Technical English style guide. And also we didn't mention it yet, but the 82079 standard for information for use.

The IEC-IEEE 82079-1 about Information Types

What was my point? Yeah, so I can imagine that when you write for a certain company, write the technical documentation, it may be really helpful to choose a certain style guide. We're going to use the STE specifications, or we're going to use the Google specification like we discussed before.

But for internal purposes, I think it can be a good mix of all kinds of existing style guides. What do you think about that?

Mike: I'd like to go back to your comment about computer terminology. It did make it into the 2017 versions. Rule 1.12-2 Computer processes and applications. So input/output processes, enter, click, digitize, user interface, clear, close, copy, system operations, boot, communicate, download. So they're all there.

And the premise of rule 1.12 is, well, the title: You can use verbs that you can include in a technical verb category.

So if it's a term that you use for your technical documentation, then you can include it. Although possibly it has also a not approved meaning in the dictionary.

But let's go back to the word sense disambiguation, which I think the simplified technical English maintenance group does not do a good job of explaining at all.

Scott: I liked that, what you were describing. And that's typically what I end up doing is picking and choosing. Because there are gaps and we also have different needs.

The people that, say, you mentioned IBM, they may have made theirs because that matches the information that they needed to standardize. But you may have other situations that they haven't dealt with yet. So it's hard to find one that answers everything.

Or we all have preferences too.

You might find one that you seriously disagree with on some point. We were talking about how many of the things are based on facts, which is nice, but not all of them.

And those points that are based on facts, that's where people have very strong opinions. And if you pick and choose, you can pick whoever agrees with you to put in your style guide.

Ferry: Are there any common mistakes that you see in existing documentation? For example, words that'll be used. I'm thinking of one example for hitting the enter button, for example, or hit enter.

Scott: That's a classic one.

Ferry: Is that the Google way of having more freedom or a less formal way of saying things?

Scott: I don't know anyone that's okay with using the word hit for pressing a key or something like that. That's usually someone that doesn't maybe have a background in tech writing, but that is a classic example. That would be extremely informal.

But yeah, I mean, you definitely see that a lot. To me, tied to that is something I definitely wanted to bring up. It comes up a lot in UX writing, and it's definitely becoming bigger in tech doc just in general, is the idea of a tone and word choice.

I did have two style guides that I wanted to recommend. One is from a National Center on Disability and Journalism. And they have a disability language style guide. And then a group, sumofus.org, has what they call the progressive style guide with more awareness that's building up.

If we look back at existing documentation, we can see places where maybe this isn't matching the world today. And we can have, whether it's an example, the way that we refer to people.

We can make this better, make it more inclusive. And these two style guides really focus on that. And I think they are a great place to draw that type of information.

I deal with a lot of existing content and having to retroactively make it consistent by making a style guide. And I would call this a mistake. This is a mistake I see a lot, just a simple example of, "Hey, every time you refer to the user, it's with a masculine pronoun.

Maybe we need to fix this because it's distracting at this point."

Ferry: Yeah. And I think what you're saying as well, and then what we've mentioned before, the Microsoft manual is constantly being updated, the specification is being updated every few years. But style guides are living documents, right?

Scott: Yes, yes. And they have updated it. That's one of, probably, the most recent things they've updated. Microsoft has a whole section, bias free communication, and they talk through it. And that's from less than six months ago, I believe, that they updated it.

How to Create Your Own Style Guide

Ferry: And also when you're going to create your own style guide, you can't make up all the rules that you want to include so you can think of things most often use, but when writing on it.

Or maybe a few months later, you think of some new rules when you're writing for different projects or the different device or software if it was a software, et cetera. And then you can add it to your style guide.

Are there any tips, guys, when let's say I'm a technical writer, or what I mean is one of our listeners is a technical writer and wants to improve the quality of his or her content. What should I do to create my own style guide?

Mike: I suggest that you don't create your own style guide.

It's a lot of work. Just spend your $30 and buy one. Seriously. Or use... There is so much existing material that is good. There's very little point, I think, in making your own. What you can do is supplement. We will use the XYZ star guide, except in these conditions.

Scott: Yes. And I think that's a great place to start it. It's a lot of work to make a style guide. Absolutely.

And if there are good ones out there, why not start with one of those? And Ferry, I think what you were getting at, the reason that you made yours is because they're not going to have everything that you need.

So as Mike's saying, pick one that has pretty much everything you need and that you agree with and think, "Yeah." Or what happens for me a lot of times is they have existing content.

So when we're picking it's, well, maybe at some point you had a style guide. And who knows? Maybe that person left, or maybe, because of the way you write, you've been consistent in your own writing. You didn't have a style guide.

It's just coming from your head. We need to get this written down because there are other people on the team and they can't see what's in your head.

So we retroactively find one that matches the way all the content has been written as close as possible. So yeah, starting with something that exists and then enhancing it where it's lacking, I think is fantastic advice. Really good.

Ferry: Yeah. And then you just enhance it with your own experience and your own ideas for a style guide. And then well I think it's the STE or it's IBM, one of those, I know those best.

For example, where one of them, maybe both are referring to the Chicago or the Oxford's manual of style. As actually what they say is everything that is not being discussed in this specification or style guide, please refer to the Oxford's or Chicago manual style. Is that what you mean with pick your own?

Mike: Not really. I mean, it's pick your guides. Because you've explained, Ferry, that the style guides, the commercial ones don't deal with all the situations. So, you have to supplement that with your own information.

So what I meant was, take a style guide and then it doesn't deal with such and such. So, you write your own style guide for the things that it doesn't deal with. Or you say, under these conditions we'll use this one, and under these conditions, we'll use that one, for example.

Ferry: So, when you would have advised someone, you would say, "Okay, look at your situation. Are you writing hardware documentation, or software documentation, or mobile versus desktop?

And pick the style guide that fits best to your way of working. Is that a good way of working?

Scott: Yeah, I think picking one, for sure. Yeah. Like Mike's saying. Look, another piece of this, the enhancing part of it, to me, the style guide, things like grammar, you're going to get that from say Chicago manual style.

So, that's not going to be in Microsoft. So, they're probably even going to say, "Hey, go use this for grammar rules," which is fine. And they're adding onto it. Even they're adding on.

But the thing that we have to add on, that's not going to be in any style guide, or that I deal with all the time or literally the styles. Now it's one thing to say, "Hey, here's how we write a heading," but the name of that heading style, the actual style, is different in a lot of different companies.

Or the lead in sentence to a procedure. There's a name for that style, but it varies.

That's why I like to have the examples because to me, the style guide is not only, "Hey, here's how I'm supposed to write things," but it's, "Here's how I'm supposed to format." And I can't copy and paste... If I copy and paste from Microsoft style guide, I still have to format it and there's still a place I could mess up.

But if we have our own style guide, I can literally copy that and paste it in. And that is huge. That to me, that's a big part of the consistency. It's not just how it's written, it's how it's tagged or formatted. They're equally important.

Ferry: And then you're talking about creating style sheets, for example, in any CMS system. 

Scott: Yeah, we need a style sheet. And then the style guide has examples that use the style sheet. So, I could copy a whole sample procedure that is written correctly, which are fake steps, but I can see how they're supposed to be written. And it's formatted correctly, so now I just have to write it using the steps that I need to write.

Ferry: So then you're automating...

Scott: Yes.

Ferry: Actually a large part of the process.

Scott: Absolutely. And that's what I think you get out of making your own. Even if you're relying on another one and say, "Hey, go over here to see how it's supposed to be written," or, "Go over here to see how you're supposed to follow grammar rules.

Here are our examples that you can copy and paste from that follow those rules and are formatted correctly."

Ferry: Yeah. It's in there. So use it.

Scott: Yes, exactly.

Ferry: Okay. Does that sound familiar to you, Mike?

Mike: Yeah, I mean, in theory, Scott, that is fantastic. I have worked for some very large organizations where the people who write the documents are not professional writers and they have not really got much of a clue about how to use their tools. So for example, Microsoft Word.

I have seen documents where tables of contents have been typed out and the page number is manually added.

I've seen heading styles that all manually applied. And using the format button rather than using a named style. And so I think there's a huge problem with people having tools and not knowing how to use it effectively.

Scott: For sure. I think the copy and paste concept helps with that. I mean, people are still going to make mistakes and do it wrong, but I think if they realize.

Tables are a classic example. Tables and lists are the things people seem to fight with the most.

If I know, Ooh, I can come over here and copy a table. And it comes in and it's actually a table and it's formatted correctly and I don't have to do it.

Wow, that's so nice because I hate putting in tables now because I don't know how to do it. So, they could still mess it up, but at least, hopefully, it makes it a little bit easier to have it done correctly.

Mike: Yes.

Writing for Different Audiences

Ferry: One thing that comes up is do style guides talk about different audiences? And actually the question is, do you need different style guides for different audiences?

Scott: Would an audience be more of a job function or experience level? Or are you thinking more geographical?

Ferry: Well, it could be either of those. So for example, I can imagine that, well, when the education level of a certain person is a bit less than another person, then I maybe want to format or structure things differently.

Scott: I'll take the easiest part of that example. The easiest one would be thinking about accessibility. There are definitely guidelines about writing content for people with different abilities, if you want to call it that. And Microsoft has a section writing for all abilities.

And they talk about, put the person first, focus on something. A writing style for someone that maybe has trouble seeing, or has trouble moving the mouse, they can still accomplish the task and get to the information, whether it's they're listening to a screen reader and writing for that.

So, those types of different audiences, yes. But I think it's going to come back to what we were talking about before.

You're going to realize, wow, writing to be totally accessible, it's just really improving my writing. It's not, I'm writing it differently for this group. It's like, this is how I should write it for everybody.

So, it's just changing your writing style in general, maybe, rather than having two, one for this group and one for this group, it's like this works even better for all groups.

Ferry: Exactly. Yeah. So maybe that's what we discussed in the beginning. So the definition of a style guide is to... Or the purpose of a style guide is to make documentation clearer. And that's that regardless by whom documentation is being used. Yeah. It makes sense.

Mike: I agree. But I think also you have to consider the audience because the style guides that I've seen don't really talk about... You're going to write for a 10 year old and you're going to write for somebody who's had a university education.

The way you write is going to be different. If you make your document accessible to the 10 year old, you're going to really annoy the post-grad. If you target it at the post-grad, then the 10 year old might struggle.

There is some middle ground somewhere, but I don't think it's possible to write a fully accessible document for all audiences, all the time with one document.

Ferry: Do you have any examples of when it was not possible or do you just think there are-

Mike: No, I'm just talking in abstract terms, but let's think about... All right, I'll change the example a little bit. Let's say you're writing an explanation of some phenomena.

If that's targeted at people who have studied that subject area, then the documents have to be different from writing for a lay audience.

And a lot of style guides, I don't think they really go into that type of... How would you really deal with that?

When I write my instruction manuals, when I start working with projects, with companies, say, "Well look, I can't do it for everybody, what are the assumptions? Who is the audience? What do they know? What don't they know? What can we assume they know."

Because we have to make assumptions about what they know, because if we don't make assumptions, when do you stop going back? When do you stop explaining? It's just impossible.

The perfect document is a document that is tailored to the individual. So you've got a hundred thousand users and a hundred thousand different documents. There's personalization for you, but from a practical perspective in the current state of technology, it's not possible.

Scott: I think that's an excellent point. And I agree with you, and it's not something that I see.

I can't think of a good example in a style guide that addresses that, but we always have a primary audience and usually numerous secondary audiences, and sometimes the primary audiences are pretty expert level users and sometimes they're very much a novice user and the writing has to be different for those two groups. They need different information.

To me, the classic example, and this is where I like again, to use the copy and paste, because you could copy it. A classic example would be something like I saw a step and it was, first step one was, open the default site. And this group, their audience is more expert users.

So when they say open the default site, their audience knows how to open something. They know where the default site is. They know how to do that. They move right on to step two.

But they know that they have novices. This is the first time they've ever done it. They read that and think, I don't know how to open something.

I don't know what a site is and I don't know what the default side is. I'm already lost on step one. So their approach, because they're writing for the experts, they wrote it like that, but they layered in additional information. They put a little show height type link that said, Tell me How.

And you could click that and then the feedback statement appeared that had sub-steps and it told you how to complete step one.

But that was initially hidden because they write for the experts. So those kinds of techniques, I think should be documented in a style guide and the style guide should make it very clear, this is the audience that we write towards. Just like it makes it clear about tone and branding and things like that.

But you rarely see that, and you're not going to see that in Google's or Microsoft's and even if you do, it's not

going to apply to your writing. But that's something that you need to capture and the team needs to be aware of. Everyone needs to be writing for the same audience within at least the same set of content.

Ferry: Yeah. Thanks for adding that, Scott. So we're talking about style guides for over 80 minutes already, so we're coming to an end. I've one last question before we wrap up, but before I ask that question, is there anything you like to add or things we didn't discuss yet, or any giveaways that you want to mention for the listeners?

Scott: It's been an excellent discussion. I've really enjoyed it.

Mike: Yeah. I've enjoyed it too Scott and Ferry, but in terms of answering your question, Ferry, no, there's nothing that I can think of to add. Sorry.

The Future of Style Guides to Improve Content Quality

Ferry: Thanks for answering that. Okay, so last question. We've talked a bit about automation. My last question is related to that.

What do you guys think is the future of style guides and improving the quality of tech writing? Are there any innovations that are, that can help us to write better content?

Mike: There are products like Acrolinx, which let you basically embed your style guide into software. There are checkers. What I would like to see is a writer's workbench.

An IDE for technical writers. You know the way that the software developers have an IDE and it types the words, and then they get a list of all the possible terms or words or whatever phrase they can use in the next bit, something like that, where you've embedded the style guide into your writing environment, so you've permitted to make an error.

Scott: Yeah, anything that automates it and makes it easier for me to realize... Like, if something could tell me, when I'm working on something, "Hey, this is in the style guide," and it just popped up, what you're describing, that'd be incredibly useful.

Why do I have to go look it up every time? Exactly. You don't see programmers doing that. They start typing a command and information pops up. It's right there.

The same people that'll say, "Oh, people don't use the help," are using it all the time, because that's help right there. And we don't have that in our own tools.

Ferry: And I think the most content management systems or CCMSs, they have functionalities to build your own dictionary, for example. There are plugins, like simplified technical English plugins. Acrolinx can scan content on STE.

Mike: Yes, you can.

Ferry: Yeah. And at the end, of course, those features like building your own dictionary are all ways to bring in your own style or to improve the quality of your content, of course.

They're all style guide related. Do you think artificial intelligence can contribute to creating better documentation or contribute to existing style guides?

Scott: If you consider the checkers a form of artificial intelligence, then absolutely. Anything that can look it over and say, "Maybe you should do it this way or this..." Or even, "This is wrong." Yeah, I think that's tied to artificial intelligence, so sure.

Mike: It depends what you mean by AI, doesn't it? I mean, There are two kinds of...

Scott: It's a bit of a buzzword, isn't it?

Mike: Yeah. I mean, interesting, about two weeks ago, I discovered that if I were minded to, I could describe the text drive term checker, as a type of artificial intelligence, which is quite interesting because I never looked at it that way. Yeah, there are different perspectives on what are... like the machine learning black box approach.

And then there's the rule-based approach. Both of those... I can only talk about rule-based, because that's all I know, but I don't see why the machine learning approach also cannot be useful.

Ferry: And then this term checker you're talking about, the TechScribe term checker, is it a STE term checker?

Mike: STE only. It can be customized, but I sell it only as a STE checker.

Ferry: I think also like MadCap Flare, maybe most CMSs have an autosuggestion function. So I think when you create snippets or build your own dictionary, and you enable the autosuggestion, a suggestion function, it suggests which words, or even sentences, you can use. Is that correct, Scott?

Scott: Yeah. And there are plugins that you can use, that'll do checking.

Kaizen has a plugin. Acrolinx has a plugin. So yeah, that's something that's growing. And I think if we had to put our finger on, where could we get the most gain and will see things changing, it's definitely this. Because this is just in its infant stages of where it could be and where it should be.

Ferry: So to summarize here. So when we can give technical writers any advice on how to apply style guides, we may say, "Okay, so just have a look around which style guides are out there already, like PDF versions. Consult them, read them, see what's useful for you, what you can use.

How you would enhance those to create your own style guide. See how you can automate things, by using existing content management systems and have a close look at new developments in the market, that can help you create better documentation."

Scott: Yes, definitely.

Mike: Yeah. I'd just like to... There are a couple of things. In terms of terminology management, there were a couple of free open source tools. There's LanguageTool (https://languagetool.org/), and there's the Vale linter.

And Vale is designed for... It makes mostly a sort of software development environment language tool and more general texts, but you certainly customize those and you can build your own rules for terminology management into those.

Ferry: Good one. Thanks for adding that. Yeah. And talking about tools, we have a STE checker one, as well. It's STE-tool.com (this site moved to https://instrktiv.com/ste/), I think. I'll put it in the transcriptions, but that's terminology too, for simplified technical English, as well. Yeah.

That's useful. Thanks for adding that, Mike.

Mike: You're welcome.

Ferry: Yeah. I'm going to thank you guys. Thanks for this interesting discussion. So, we've talked about a lot of things, all related to style guides. And thanks for listening, everyone.

Scott: Thank you for putting it together, Ferry.

Ferry: My pleasure. My pleasure. Thanks for being guests. And thanks for sharing a lot of expertise on this topic. I'm sure it's really useful for all the listeners and will help them to create better content. 

Other Tools, Guides and Sources

LanguageTool: https://www.languagetool.org/ (scroll down to get the 'Desktop version for offline use', which is customizable)
Vale: https://github.com/errata-ai/vale
Vale Server: https://errata.ai/vale-server/ (it's commercial, not free)

Economist style guide: https://ukshop.economist.com/products/the-economist-style-guide-12th-edition?redirect=International

Read Me First!: A Style Guide for the Computer Industry https://www.amazon.com/Read-Me-First-Computer-Industry/dp/0134553470

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. 

Ferry Vermeulen is a technical communication expert and director at INSTRKTIV. It's Ferry’s mission to create digital user instructions for all products in the world. Listen to the INSTRKTIV podcast on Spotify or read one of his latest blog articles.  Linkedin I Spotify I YouTube I Facebook I Twitter