You’ve been there, I know I have. Somebody complains that searching doesn’t give the expected result. If the obvious matching document shows up at all, it’s ranked too low. So you give it the ol’ quick’n’dirty:
- Repeat the document’s keywords to boost its ranking, “delete file delete file delete file”.
- Turn dials on the search engine until the document show up first.
Congratulations, your search engine is exquisitely tuned to find a single document for a single query. Close that ticket and move on. Don’t forget to open another ticket for the new set of complaints you’re about to get.
Other symptoms
If your users actually find what they’re looking for, they spend extra effort to scan for the relevant parts. You’ve added insult to injury by using bold for UI labels while your teammate uses italics.
Or tech support stops using your content, maybe even writing their own docs for stuff you’ve already covered. You wrote a knowledge base article for the auto-update widget and they wrote their own article for it too.
Your translation costs are growing faster than your doc set. Shouldn’t localization per word hit a plateau as your content grows?
Your users feel like the short guy in “Who’s on First”. Turns out the dev team calls it footwear_analytics, the marketing team calls it Sock Stats, your competitor trademarked it as Footalitics™.
Cure it with consistency
These are symptoms of inconsistency. Inconsistency is like scurvy. The symptoms are gross, gradual, but the cure is simple and effective:
- Use the same words to mean the same things.
- Use the same visual styles to show the same things.
Your doc team can choose a level of consistency from cheap’n’easy to nasty-if-necessary, or some combination that you’re happy with.
Style guide
This one is the easiest. Just agree on what you call things. Start with a table for product and feature names. Maybe add some rows for the industry terms that you use, avoid, or re-define.
Add another table for visual elements. When should you use ordered vs unordered lists? When should tables have header rows or columns?
Don’t forget bold, italic, colours, fonts, and spacing. Here’s where a good relationship with the design team pays off. I’ve had success just telling them what I need to signal with formatting and asking them to make the actual design decisions.
Just as important is to enforce the style guide. Does your team’s review process include a tick box for style guide adherence? Is the style guide reviewed regularly, or at least updated to match current usage? Does every update to the style guide include a heads up for the team?
Plain language
It takes a big writer to use “visualize”. It takes a bigger doc team to use “see”.
Tech writers should use plain language already even when they don’t know that Plain Language is a thing. But it is, and it’s good to embrace it officially as a team if only to remind ourselves that it’s too easy to drift away from it.
Ironically, governments are excellent sources for plain language initiatives. There’s even an ISO standard.
Controlled vocabulary
This one is more restrictive than a style guide. Librarians are big on this for classification.
In tech writing, I’ve only seen this in big organizations where multiple doc teams share a list of allowed terminology. The goal is to make content reusable across departments or products.
And you can encode your controlled vocabulary with metadata. There are a few conventions to mark up or add to your content to make it more search-engine friendly. That includes marking up titles and summaries, or adding location and revision dates. Semantic Web and schema.org are maybe the most popular metadata conventions.
Restricted language
Some industries, especially those that are regulated, use prescribed subsets of a language. We’re not talking about just product names. Restricted language specifies how to use verbs and other grammatical stuff too.
While the rest of us write “Happy birthday!”, doc teams in the restricted language world might have to write “Your date of birth is now”. Arguably, restricted language purposely ignores the last C.
Restricted language is about shrinking ambiguity to a minimum, typically in procedural content. When there’s a risk of something exploding if your user “cuts” the blue wire instead of “disconnecting” it, then you should probably use restricted language.
It also makes it easier for non-native speakers to follow your content. That usually means that translation is cheaper, too.
For example, Simplified Technical English is the lingua franca in aerospace.
Pushing past the explosions
It’s not all about avoiding explosion. If you’re really into this, you can explain things with only the most common ten hundred words in the English language.