Product documentation can potentially be confusing, incoherent, and ambiguous in many situations. Recognising language ambiguity usually takes months, if not longer.
Several aggravating factors include:
- A constant need to churn out or translate volumes of documentation, manuals, and working standards.
- Rarely questioning the relevance or validity of legacy documentation.
- Allowing unclear parts of your technical content to snowball into substantial chunks that will eventually make up parts of your “user-unfriendly” help guides.
Finally, let us not forget the insidiously familiar workplace jargon that often explains why we tend to ignore simpler alternatives that could help us express our thoughts with greater clarity.
From workplace jargon to user-friendly words
Sometimes, realising the level of complexity of one’s technical content involves an epiphany of sorts once the writer catches a glimpse of technical writing in Simplified Technical English (STE). This is true for one of our clients, who is both an experienced technical author and documentation manager:
“A training course helped me better appreciate the objectives of Simplified Technical English from a technical writer’s perspective. I like the fact that STE promotes the use of less complex sentence structures and does away with unnecessary words like: ‘would’, ‘should’, and ‘might’.”
Do we have a problem? If so, fix it!
For example, if you look up the meaning of the word “fix” in a standard dictionary, the definitions are aplenty, from “fixing a technical difficulty” to “fixing up a meal in the kitchen”. Given the many possible meanings that hold true for the verb “to fix”, one could also distil as many interpretations of the word in a sentence.
According to Simplified Technical English, Issue 7, January 2017, there is a solution for this. Instead of “fix”, synonyms such as “ATTACH*”, “SET”, “REPAIR”, and “INSTALL” powerfully extend our understanding and knowledge of what “fix” really entails when paired with various contextual clues.
© ASD, 2017. All rights reserved.
The next five words: are you thinking of these too?
Keeping in mind that these are not the only unproductive words I talk about in my workshops, they are among the most frequently discussed ones.
© ASD, 2017. All rights reserved.
The word “should” usually indicates duty or correctness that points to a desirable or expected state. However, it still allows the possibility of non-compliance. “MUST”, on the other hand, makes it clear that the instructions are mandatory and leaves no room for a different reading.
© ASD, 2017. All rights reserved.
Besides the roughly 900 approved words found in the STE general vocabulary, the STE specification also includes a list of non-approved words. “Would” is one of those words that is easily replaced by a more straightforward and approved STE word like “CAN”.
© ASD, 2017. All rights reserved.
In the STE general dictionary, the approved word examples in the 2nd column are very useful to technical writers who are transitioning from Standard English to Simplified English. This is because they provide the writer with the correct use of words in a real-life context that would be difficult to think of independently. Here, we see that “CAN” is once again a very helpful alternative to the verb “may”. Using too many words that point to the same or similar meanings can be, at times, overwhelming for your readers, especially when documentation becomes lengthier and more detailed.
© ASD, 2017. All rights reserved.
By this time, the effects of STE on everyday words that pose as potential roadblocks to concise writing are clear. Instead of “transfer”, STE encourages the use of “MOVE” or “INSTALL”. This adds granularity to one’s choice of verbs, making technical work instructions more detailed and easier to follow.
© ASD, 2017. All rights reserved.
The preference in STE for the verb “MAKE SURE” over “confirm” is again another unique characteristic of this standard. This is very likely so because the maintenance committee (made up of a diverse mix of linguists, engineers, and translators) deems “MAKE SURE” a more fitting word with more frequent usage to back their word choice.
What are some popular words in STE that trained technical writers have adopted to date?
We asked over 30 technical writers and this is by far the most comprehensive response to date:
“My favourite STE verbs are ‘APPLY’, ‘ATTACH’, ‘MAKE SURE’, and ‘SHOW’. The verb ‘APPLY’ has multiple use cases for our documents. The verb ‘ATTACH’ is a great utility verb because common alternatives like ‘mount’ are not approved. The verb ‘MAKE SURE’ is extremely helpful in cautions and warnings, as well as in some procedural steps. Finally, the verb ‘SHOW’ is extremely helpful when I write about background processes and how things work in general.”
STE as a game-changer in our technical communication landscape
Can you envision a future where STE serves as the primary language reference for content creation and development in your field?
We would like to hear from you. Leave your ideas in the comments section below!
Learn more about what STE can do for different types of documentation here.
Thank you for reading, we hope you found this article insightful.
Want to learn more or apply to the TCLoc Master’s Program?
Click HERE to visit the homepage.
Thanks from the TCLoc web team.
