The quickstart guide may need to introduce technical terms or jargon, but it will be useless to new users if it doesn't define these terms and use plain language synonyms users can understand. Learn how to use accurate plain-language substitutes for technical terms, options for defining terms, and why you should avoid jargon.
- You're caught in a bit of a predicament when you're writing a quick start guide. To be accurate you may need to use the technical terms associated with the product, service, or tool you're trying to explain. I mean, if you're writing a quick start guide for speech recognition software, for example, you may need to write this sentence. "To use a Bluetooth microphone, plug its dongle "into a USB port on your computer." The word dongle is the correct technical term for the connector that plugs the microphone into the computer, but it's a term some users won't know.
Their confusion about the word dongle might just complicate their efforts to get started with the speech recognition software. That's where plain language comes in. Plain language isn't dumbed down wording. It's an overall approach to communication where the writer uses terms the reader can understand and act upon. When you're writing a quick start guide you should never think of plain language versus technical language.
You should plan to use both. Here are three simple ways to use plain language in your quick start guide. We'll use the microphone sentence as an example. Place the plain language term right beside the technical term. Placing these synonyms near each other prevents the reader from having to look elsewhere to find out what the technical term means. We've already looked at an example where the writer used the technical term dongle first and followed it in parentheses with the plain language term connector.
If you believe the technical term is really unfamiliar to readers, you can reverse the order and write the plain language term first and follow it with the technical term in parentheses. Use words that indicate you're defining the technical term in plain language. With this strategy you use words such as which means that or which is defined as, or others, to cue the reader that you are defining a technical term.
Here's an example from the Orange Valley Insurance quick start guide to finding a doctor. "If you need surgery, you may choose "to visit a non-participating provider, "a term which refers to a physician "who does not have an agreement "with Orange Valley Health Insurance "to provide covered services to members." Finally, create a short glossary. A glossary is both a good thing and a bad thing. It's a good thing because it's an organized, alphabetized place in your quick start guide where you can park all the definitions of technical terms.
If you keep your glossary short, your reader will be able to locate it at a glance and read the definitions as needed. But a glossary can be kind of a bad thing because your reader will have to look at a different place to get definitions. This looking away from what they're reading can be distracting. Now on to another important use of plain language. When you commit to writing your guide in plain language you also commit to avoiding empty business jargon.
You commit to choosing accurate, simple, useful words instead of fancy words or biz speak. For example, people who write in plain language don't use the tired phrase value-add. So in your quick start guide to chemistry in your classroom grades six through eight, you'd never write, "Click the Investigations tab to access 17 value-add "chemistry lab exercises you can use in your classroom." Instead, you'd choose one of these plain language substitutes, the words additional or challenging.
The danger with biz jargon is that we become so accustomed to it that we don't even notice how meaningless it is. So be on your guard. Be ready to use plain language substitutes for these empty words and phrases. Instead of synergize, try cooperate. Instead of drill down, consider access, navigate, or examine. Plain language isn't just nice to have when you're writing a quick start guide.
Plain language words are the ones you choose to fulfill your obligation to your user.
- Explain the difference between a conceptual guide and a procedural guide.
- Determine how to address a user when writing a quickstart guide.
- Recall a tactic that helps avoid too many notes.
- Identify the benefits of using plain language.
- Name the most important aspect of formatting.