“You keep using that word. I do not think it means what you think it means.” (The Princess Bride)
The purpose of technical writing is to share information, not documentation. Content can be both perfectly spelled and perfectly meaningless. Just ask anyone who has wrestled with a legal document, municipal regulation or software manual.
“Plain Language” offers the following guidelines for creating more effective – and meaningful – content.
One size does not always fit all
Divide your audience into user groups based on the type of information they need and how they will use it.
For example, an employee trying to submit a vacation request through the company’s HR system probably doesn’t need to know how to run compliance reports for that system.
Don’t overwhelm your reader with information they don’t need and will not use.
Yeah, I’m talking to YOU
Engage the reader by addressing them directly, using second person pronouns (“you/your”).
Get to the point
This isn’t a scavenger hunt.
Put key information up front – bonus points for a summary. Move detailed discussions to the back and add links between the two so that readers can click to take a deeper dive if they want to.
Save the cliff hangers for that novel you’ve been secretly working on.
“Bite-sized” for easy consumption
Don’t force your reader to wade through endless blocks of text. Use “info-chunking” to break content into smaller topics that are easier to consume.
Show them the way
Use headings and transition words, like “then,” “next,” “before,” and “after,” to help your reader navigate through the content.
Headings should be short – 5 words or less – but informative. For example, “Configuration Options” is shorter but “Configure Remote Workload Controls” tells the reader what type of options are discussed and what purpose they serve.
Choose your words carefully
This is not the time to unleash your inner Roget’s. If you can say it in 5 words – don’t use 15.
- Use active verbs – in their simplest form
- Avoid excessive jargon and “techspeak”
- Use short, clear sentences – keep your subjects, verbs and their objects close
Add a little “eye candy”
Visual elements, like colors, graphics, charts, lists, and tables, are a great way to break up big blocks of text…
…BUT make sure they are relevant, appropriate, and don’t overwhelm your document.
Too many visuals can be distracting, rather than helpful. They can also increase file size and load time – which can be an issue for remote or mobile readers.
Lead by example
Examples help readers make the connection between “concept” and “conduct.” Use common scenarios with which your readers can easily identify.
Thou shalt – NOT
“Shall” sounds stuffy – and its meaning isn’t always clear.
Instead of “shall” use:
- “Must” when something is REQUIRED
- “May” when it is OPTIONAL
- “Should” when it is RECOMMENDED
And finally…
If you need to diagram the sentence to figure out what’s going on, you are not using Plain Language.
Is your documentation difficult to understand? We can help! Contact MATC to learn how our technical writers can help you create clear documentation that will save you time and money.
Related Blogs
Why Document Formatting is Important: Designing for Readability
