The function can be fulfilled by content writers, tech support, PMs, etc. The guide includes practical examples to make the guidance clearer. It includes subjects such as chatbots and cloud computing, plus much more.
What it also is, in my view, is another good example of how documentation should be done today. Have a look yourself and see what you think. Email Us. Search Search. Top 10 tips for mastering Microsoft style and voice. We welcome your feedback about the Microsoft Writing Style Guide. Contact us at msstyle microsoft.
Skip to main content. This browser is no longer supported. Download Microsoft Edge More info. Contents Exit focus mode. Whereas ours is, this is how we do it because we only really have one situation that we're having to deal with. So, there is that kind of interesting difference between them. And, maybe the only difference may be publishing something online or in print. Scott: I used to see that a lot in style guides.
That's an interesting thing to bring up. And, we would even have different writing guidelines for print and online. I think a lot of that has gone away, but you do see that now. And even some of the examples that you mentioned, now I think what's happened is it's become, hey, here's how we do it for mobile. And here's how we do it for desktop. And, I have seen even writing differences certainly between those two situations.
But, I don't see the print and online as much anymore, but I still think it's valid. Ferry: Yeah, exactly. But, for example, when you refer to a certain section in the online documentation, online help, you can, you can place a hyperlink to that section and you can say, okay, when you place a hyperlink, it should all be capitalized and not italic, for example.
And, you should place a hyperlink. But, when you print your documentation it should be italic. And well, of course you can't place a link to that part. And, that is something that can be part of a style guide. Scott: Yeah. For me, a lot of that has been handled with CSS. So, it's sort of automated. So, the style guide might more say, hey, you need to use a cross-reference because we've set up the cross-reference to handle these differences. So, the writer doesn't have to deal with it as much.
But, there is something in that style guide that says, hey, you have to use in that case a cross-reference because it's going to adapt itself for online and print.
So, I do think it's still there. It's a really interesting example actually. 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.
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-STE specification.
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.
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. 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.
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'. 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? 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.
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? For example, if they're focus is, "Hey, this is going to be used almost exclusively on a mobile device.
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. It really depends on the group. 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.
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. 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-.
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. 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'.
Ferry: By the way, guys, the Kohl style guide and the ASD-STE 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. 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 , the latest version of the ASD-. 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?
Mike: That's right. And the writing rules were simplified and changed also. It's not just dictionary maintenance. 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: 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.
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. 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 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. 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.
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. No, sorry. 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. 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. I copy it and paste it in. It takes maybe a minute. 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. 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. 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. 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. They capitalize things a little bit differently, so there are small differences. 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? 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. Mike: Yeah, well, STE says No, it doesn't tell you how to write your headings and that's for your style guide to specify. Mike: I don't think so. 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. 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?
0コメント