Writing about technical things is hard to do well. These are some of my tips for communicating about technical things which should help whether we’re asking questions or giving answers or just providing documentation.

Be VERY specific

When writing about an issue, whether we’re asking a question or giving an answer, be very specific about expectations, actions performed, and the result. Include screenshots, links to documentation, stack traces, full error messages, data sets, etc. to expand on our expectations, actions and results and our reasonings for those things. This will be a lot of information and likely too much information but we have a plan for that later.

Do not use pronouns for systems

We’ve all heard issues described like “It sent a request and it sent a response but the response was not expected so it failed to do the thing” which infers that there are at least 2 systems involved but we have no idea how many systems because we call them all “it”. This reads much clearer when we say something like “System A sent a request and System B sent a response but the response was not expected by System A so System A failed to do the thing.” Typing less characters does not make us more efficient. Communicating more clearly makes us more efficient.

Define Acronyms and Abbreviations

I like to pretend I’m the founder of the Association Against Unnecessary Acronyms and Abbreviations (AAUAA). The first rule of AAUAA is that the organization must always be mentioned phonetically so that we can remember the pain caused by the overuse of unnecessary acronyms and abbreviations.

We shouldn’t avoid using acronyms and abbreviations but my guideline is that if I’m using an acronym or abbreviation for something that I don’t know is universally known then I’ll define it at least once before using it in my communication.

Write a rough draft

Our English teachers in school were on to something with rough drafts. If we are very specific, avoid pronouns for systems and define our acronyms and abbreviations then we are going to write entirely too much. No one is going to want to read all that! Don’t delete all that information though! We might need the information later. Instead use all the information we wrote to write a more concise, final draft of our message.

Write the Bottom Line Up Front (BLUF)

Even after we write a more concise, final draft there still might be too much information for busy people to read. Take all the most important points of our message and put them at the beginning of our message. This is our BLUF. It allows readers to get the gist of the message first, then our more detailed explanations can follow later. For more on BLUF, go here: https://en.wikipedia.org/wiki/BLUF_(communication).

Break up the text into sections

Writing about technical things is hard. Reading about technical things is also hard. Make things easier on our readers by breaking text up into bite-sized sections to make it easier to read and focus.

Some ways to do this are:

• Bullet points, like this!
• Headers, like I’ve been doing.
• Horizontal lines

That’s just about everything I know about writing good online communication. Good luck!