A Technical Writer’s Almanac: An Ode to Practicality, Readability, and Their Necessities

Freedom of speech is overrated. There exists only absolutism in the realm of writing. There is only a handful of ways to express something and as soon as you go beyond what’s made available to you, you will find yourself and your work ostracized.

Now, this is merely a dramatization of what I felt about technical writing in IT. It genuinely feels refreshing to be able to include a hook before getting into the bulk of what I’m about to write. There are no hooks in technical writing.

Rather, you’re on the hook if you manage to leak a drop of humour in any of the documentation.

There’s an overlying assumption that people in business are capable of thinking of only one thing, of which their livelihood depends on. That’s a mistake. We are always looking to fill ourselves with something interesting. A life is an amalgam of distractions. A good life is therefore a life that has seen the fulfilment of those distractions.

Of course, people have priorities. But if that item in that list of priority can be enjoyable, that’s where technical writing can really lighten up our days. Technical writers can be that bartender who lends a ear to all your tirades and slide you a shot of Tough Day (hold on, did I just make up a new cocktail name? Will it make it to a page on The Essential New York Times Book of Cocktails?) in return. It’s on us to make sure everyone gets their information deliverables that’s not only robust in usefulness, but also in readability. The ideal content today needs to be a jack of all trades.

Easier said than done. If you want your content to pack a punch, you need to be wary of things that possibly alienates readers, such as idioms. The presumption that usage of idioms may attain a colloquial tone can instantly cut off a very important connection between the writer and reader. Especially when technical writing is about simplifying concepts that are otherwise very intimidating subjects, the reader must be convinced that the writer will not forsake the readership in a mire of technical jargons. Readers will take the meaning of idioms literally. Remember, you’re building a bridge for them to cross so if you tell them the next step of getting across the bridge is falling off, just for good humour, they will in fact fall off the bridge as you’ve instructed them.

Tech leviathans like IBM, also have something to protect – universal consistency in style and tone. It’s like when McDonald’s had to worry about franchises in other states and countries altering their menus. So in the end, this all boils down to quality control. Writing isn’t considered a team-driven activity, but if you’re with the big guys like IBM, Amazon, Google, Microsoft, or Apple, you need to get into that team mindset. With release cycles that are targeted all across the globe, there’s a good chance that your content will be translated into other languages. You’ll quickly realize how strange English is when you receive queries from translators. The translation queries coming from English-as-a-second-language individuals will have you sweating the next time you try to use idioms.

Imagine, upon using idioms in your writing and then saving your changes, this pops up:

“Are you sure you’d like to sacrifice practicality for figurativeness?”

You click ‘Yes’.

“Sorry, that option is no longer available. Please try again.”

You’re one stubborn grub who still uses idioms and save. The style checker got an upgrade since:

“1 Critical Error: The following phrase must be written verbatim.”

Writers, let’s not have developers come up with a software solution like this. Because the next thing you know, you’ll have “Wrote clear, instructive copy for error messages” under your technical writing experience on LinkedIn. Anything will be better than writing error messages for a living.

Quality control is a lot to ask for when you have thousands of pixellated information that’s already been published and maybe even distributed more than a million times to users of a particular line of products. Imagine having to overhaul those content then finding a way to disseminate the new content. But in the end, you’re doing just that, which you think is “a lot to ask for”. Quit crying. Think about the translator whose onerous duties involve pushing through your pile of ill-placed sense of humour and do your level best to avoid using them. It will save lives.

Be comprehensive, but don’t be too comprehensive. You’ll understand that when a page of patch notes, for example, will list all new features, fixes, and changes. You’ll be surprised how many of the tech giants just list them in bulleted points without any logical order. Yet alienation can also happen if you dumb down too much. You should always be mindful of who you’re writing to – a green neophyte or a veteran user.

Think twice before you use a metaphor. I know you resort to metaphors because a) you don’t know how to explain it better in simple words b) you want to feel smart because you weren’t able to find a way to explain yourself c) your love and concern for humanity is at an all-time low because technical writing has deprived you of your creative faculties. I personally know the desire to use a metaphor derives from the above symptoms, because I remember being deprived to such an extent that explaining to a translator not in metaphorical terms but in mathematical terms made sense.

This was how it all played out:

Mr. Translator: Is this sentence, “Latch wait time percentages higher than 15% to 20% is considered high.” equal to “Latch wait time percentage higher than 15% and reaching to 20% is considered high.”?

Mr. Tech Writer: Yes, latch wait time percentages that are higher than any numbers between 15%~20% (that is, higher than 15, 16, 17, 18, 19, or 20) is considered high.

If x>15~20%, where x = “latch wait time percentage”, that latch wait time percentage is considered high.

Notice how I used ‘=’ instead of “denotes” for the sake of universality. I would’ve loved to use “denotes” because there are beautiful words ready to be employed, lush with history and linguistic significance. Same thing with “that is” where I could’ve opted for a latin abbreviation “i.e.“. Truth is, you’re writing for users, not logophiles, who are trying to learn how to use a product which is completely unrelated to whether their level of appreciation for diction is the same as yours.

In all seriousness, the original text,¬†“Latch wait time percentages higher than 15% to 20% is considered high.” is poorly worded without a doubt. Also take note how time is wasted on something as trivial as this. Everyone comes out victorious with succinct sentences.

It could have been something like:

“Latch wait time percentages that are higher than 15% but lower than 20% is still considered high.”

Or simply:

“Latch wait time percentages that are higher than 15% is considered high.”


If you have trouble putting a harness on your free soul and your expressive temperament, look for opportunities to write for an internal audience. There are quarterly newsletters, content hubs, blogs, podcasts, and so on where you can write to your heart’s content.

The best way to address all of these concerns is to have the right contacts within your reach. Good communication matters in technical writing more than anywhere else. Your book of antidotes is your book of contacts.¬†Whether that’s when you need feedback from the customers who are reading your content, or double-checking with developers who are subject matter experts on the products, ensure the issue surfaces before someone else picks up on it.

Remember, you’re the bartender who thinks of ingenious ways of mixing all the information in one concise drink, and one of the vanguards in the front lines of technical development who discerns what’s too technical and what’s too condescending.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s