Let's Tech Communicate
November 2018
There’s nothing like a good family movie full of terrible puns and toilet humour at this time of year, so this month’s LTC comes with a little eighties’ movie flair.
You keep saying that – I do not think it means what you think it means…
Did you know there are 129 uses for the acronym BA? And that’s not counting the initialisms… It’s inconceivable!
Overusing acronyms severely reduces readability, and makes communication unnecessarily bureaucratic. As technical writers we have a love/hate relationship with acronyms, especially when wielded by non-TCs. Is your company’s style guide excluding or alienating your reader? Check out Word rage: how acronyms alienate your reader .
Sometimes the way forward is the way back…
Those who don’t learn from history are doomed to repeat it… and I was quite taken with these little blasts from the past!
Did you know you can measure plain English mathematically? The Flesch Reading Ease Formula is not a new thing – Rudolph Flesch developed it in 1948! But we don’t see it used much these days. It’s a shame, because this is one of the concrete ways we can prove plain English works. The Flesch Reading Ease Formula has become a standard readability formula for many US Government Agencies, so as more governments around the world get on board with plain English, we may start seeing the Formula coming up more often (in spite of its ambiguities).
“2000 years ago, the rules of storytelling were laid down by a man who was, according to legend, the last person to know everything”… Ravi Shankar Rajan takes us all the way back to Aristotle in How to be An Insanely Good Writer . In fact, Aristotle’s tips aren’t just applicable to modern fiction, drama, and film, but to technical writing and content development.
It’s a tale as old as time…
…but it doesn’t have to be.
Why do developers write horrible documentation? The answer is not that developers don’t write well or can’t write documentation. They certainly could…if they weren’t developing that product. The problem is that developers are too close to their product. Don’t get me wrong; this is a very good thing. If the developers weren’t that close, the product would be horrible, half-built, and quasi-functional. However, developers just can’t have the viewpoint that’s needed for good documentation.
Poor documentation casts a shadow on a company’s reputation . As TCs we know this to be true. The trouble is convincing SMEs, and sometimes our own bosses, that it’s true. Many companies consider any kind of user documentation to be of great importance and but disregard the company’s internal documentation. If you’re struggling to change hearts and minds in your company, direct them to Four Main Reasons Why Poor Documentation Can Spoil Your Reputation as a Vendor .
And on that subject…
When should you fix a broken process and when should you simply throw it away? Sometimes we continue on within broken processes for years; it might make sense to systematically try to fix broken processes — to a point. Tom Johnson reflects on the throwaway mentality in our culture and how it affects our documentation processes.