Why should you listen to me
Why are you telling me how to communicate? Who are you? This must be the immediate question that you have. Heh, we all know how to communicate; even my 3 year old can communicate clearly enough that her father can understand her!
Alas no, not everyone knows how to communicate. You really have no idea how much frustation I’ve collected throughout the years because of unclear communication (from both sides). Why can’t everyone just say the thing on top of your mind, clearly, the first time round, and nicely too?
I would say that I’m in a unique position to talk about this issue. My day job has been writing code, and also telling others how to write code, and listening to pitches on new software features and pitching others on new software features. My night job has been telling stories and dispersing instructions to my 3 kids so that they can laugh and cry- laugh when they hear a funny point of the story, and cry when they understand what they have done wrong to merit the punishment. So I think I am fairly good at this since I’m doing this day and night. Thinking, condensing my ideas and then packaging them in a form that others can readily unpack as it is critically important for me to do my job.
Wearing a programmer’s hat especially helps in this situation. You might think otherwise because writing code is primarily about talking to computers; so it doesn’t matter how clearly you can write, because the computer can parse through the most obfuscated code correctly. But you can’t be more wrong.
Writing code is also about communicating in English with your future self, and the poor souls that happen to maintain your code, as much as communicating in binary code with the present computer. It’s simply not good enough that your code has no obvious bug; it has to obviously have no bug. And if you can’t make your intention clear to the future programmers, they might deem your code has bugs even though they have none. So you have to make your logic and your intention clear: you have to use correct variable names, consistent coding format and explanatory comments to ensure that your code reads like a good story. Your code has to flow with the logical structure so obvious that it practically screams “look at me! I’m obviously right! It’s even written in the rigorous theorem- lemma- proof style to welcome everyone’s checking, and it’s also sprinkled with the George RR Martin-like prose so it’s super readable!”
I would argue that being a programmer actually helps you to be a better writer. Writing code forces you to think clearly and structurally because machines can only understand strict instructions. By comparison English offers too much leeway and ambiguity which is the enemy of clear communication.
With all these super long introductions; here come the rules of thumbs that I find useful in clear communication, and they do both verbal and written communication. It is meant to be a general guideline but I try to sprinkle it with vivid examples so that I can also..er..communicate clearly.
“Why should you care”?
If you care about a topic, you are willing to put up with any bad writing in order to get to the bottom of an issue. The converse also holds: it’s hard to get one to read a piece of writing, no matter how interesting it is if he is lacking interest. Newspaper front pages are eye-ball grabbing designed to hook the readers. Of course they have to be this way, or else how to get readers salivating and buying the paper? Whether the content lives up to the hype is an entirely different matter of course.
In technical writing, overhype and underdeliver is frown upon. But the same principle applies- you need to put the most important thing- the motivation, the salient point- at the very start of the conversation, whether in verbal or in writing. Right before you describe your brilliant new ideas to your colleagues, tell them why they are so important that you would wish to wake them up in the middle of the night in order to tell them. Right before you start your call-to-action memo, explain why it is a must read? What would be the consequence if they don’t?
“Why should you care” can also be translated to “putting first thing first”. When you want to initiate a ticket, a conversation or even a PR, ask yourself “if the readers can only take away one thing from this conversation, what would that be”? And that thing should be your title, your opening paragraph.
Humans remember only the headlines.
I hear you asking ; but what if they couldn’t care less? Then maybe the ideas aren’t so great and it’s better you keep them to yourself at this point of time.
Be precise and concise
In technical communication, being precise is important. Don’t say “the dialog box has a bug”. Well yes, I know it has a bug, but exactly what? Which dialog box? What kind of bug-compilation error or runtime error? What do you expect to see? Can you reproduce it in a minimal example?
It’s much more meaningful to say that :”I click on the button XYZ and out pop a dialog with Alignment Index name, but then after 3 seconds it starts blinking with red color and then it crashes and brings down the whole application. It should never ever crash”. Notice that you have an action sequence, and you describe what you see, what is happening and why it is wrong.
Also, notice that we use the exact words like “Alignment Index name”, “blinking with red color” so that the user knows what to actually look for. The more precise your description is, the easier the user is going to build a mental model for it and they can understand it better. That’s why having a good command of English is important because being the most used language in the world, it has a large number of vocab and we have unique words to be used only in unique situations. So learn and master English!
Being concise also means trimming the fat. Fats are there to make the food tasty and the conversation fluent. But in technical documentation we strive to bring the point across crisply. Too much fat in the form of weasel words can obscure the communication and drain the patience of the readers. Instead of acting as a seasoning for food or thought, they might repulse people.
One exception is in verbal communication, words like “Umm, ahh” in verbal are fine. I understand that you need them to provide space for your thoughts to reorganize in the background- but don’t overdo it.
One way of being concise is to just explain the difference. You do expect that your readers have some background in conversed topic. So you can skip all the background talk. If you find that you can just can’t bring the point across without spending 10 minutes rambling around, then just list down what you want to say, and say it. Technical discussion is not dinner talk whereby rambling is encouraged to keep the conversation flowing. It’s meant to drive home a point and not waste everyone’s time.
Does it even make sense later on?
I know I said that brevity is good. But you do have to care about how other, future colleagues would read the piece. They don’t necessarily have the background, and that’s onto them to read up the relevant backstory. But you do have to make it easier for them to digest your cooking.
In programming, we do have a few conventions to maintain the readability of the code. One of them which is also applicable towards day to day communication, is having explicit and descriptive variable names. When I see a variable with a meaningless name I really want to puke; what’s so difficult about calling it monkeyIndex, numbersOfMonkeys instead of i and Count? i and Count could mean donkeyIndex or numbersOfDonkeys, so how am I supposed to tell the difference? Ditto also for verbal and written communication. “Jola and Karet are best friends but then he betrayed him”– woa, who betrayed who? Jola betrayed Karet or vice versa? It might be obvious to you in the heat of the moment who’s right or wrong, but for some future readers, they wouldn’t have access to the context of the conflicts, so they wouldn’t know.
A lot of times, a piece isn’t making any sense because it lacks the context. You have just described meticulously how the software behaves under a string of inputs, and then you stop abruptly. And then what? What do you expect? It’s not sufficient to say that “after I click on XYZ I see the color blue”. You might be clear why color blue is a bad color but not everyone else; you have to fill everyone in, what’s wrong with color blue? Leaving important context out is sure as hell to confuse people to no end.
Highlighting the important difference with the expected behavior is a great way to make the future readers grok the whole piece. Human minds work in such a way that it seeks wonders that contradict the expectation. I dread reading technical reports that drool out pages and pages of technical details, numbers, equations and tables, but never ever tell me what’s the significance of them, or how I should update my prior knowledge, or how to make use of the equations and numbers to change my working behavior (AKA what’s in for me?).
Show, don’t tell
They said a picture worth a thousand words. So I’m not going to elaborate on it. Just read the following (already very descriptive) paragraph:
In AutoCAD there is this very interesting behavior: when you want to snap to a point and you move your mouse cursor slowly towards it, then you will find that the point is as if it’s exerting a pulling force towards the cursor, and the cursor will speed up and fall into that point like Apple falling down from tree to the ground.
I would like to say that this is already a very good piece of writing; you can literally imagine it in your head and trace how the cursor is moving around, with all the slow motion effect and the sudden speeding up.
And try to compare it with a gif image:
The gif image casts a more lasting impression; it beats the writing description every single time. We are all visual animals after all.