8 Writing Tips for Software Professionals

Original post at optimizedbyotto.com/post/writing-tips-for-software-professionals

People usually associate advanced software engineering with gray-bearded experts with vast knowledge of how computers and things like compiler internals work. However, having technical knowledge is just the base requirement to work in the field. In my experience, the greatest minds in the field are not just experts in knowledge, but also extremely efficient communicators, particularly in writing.

Following these 8 principles can help you maximize your efficiency in written communication:

1. Less is more

In a workplace setting, the ability to summarize something in three sentences is far more valuable than the ability to write fancy-looking research papers. Forget school assignments with minimum lengths – in reality, you need to put in effort to specifically keep it short.

2. Start with the solution or the ask

Unless you are a professional novel writer building up an arc of drama, your readers are most likely not captivated enough to read all of your text fully. Therefore, you need to put forward your main suggestion or request as early in the text as possible. In ideal cases, the main message you want to convey is already in the title.

3. Show the facts, with examples

If you are an expert, people will value your opinions. But it is always much more compelling if they are delivered with supporting facts, numbers, timelines, and references. Ideally, there is a reliable source to refer to or an indicator or statistic to look at, but a couple of anecdotal case examples also work well as both evidence and as a concrete story to showcase cause and effect.

4. Always quantify

A number is always more expressive than an adjective. Instead of a vague "expensive", just write "500 USD/h" if the price is known. Don't state that something is "significantly faster" as it does not actually mean anything. Saying, for example, "travel time decreased to 5 hours (down 30% from 7 hours)" paints a much more accurate picture.

5. Include links and references

Instead of a verbal reference like "read the report for more," make a service to readers and include a direct URL they can simply click. When describing a system or a problem, include the documentation link or issue tracker identifier.

6. Explain why it matters

After stating facts, ask yourself "so what?". Cater to readers who are not fully familiar with the domain by being explicit on why something matters and what it means, in as concrete terms as possible.

7. Ask feedback from one person

Before sending out a text to a large group of recipients, ask one person to read it first. If your main message does not get across, iterate on your text until at least one person understands it in the way you intended. If the text has great significance, you might continue to ask for feedback from two or three more people, but remember that everyone has an opinion, and there is no guarantee that getting more opinions will converge on one opinion. Asking multiple people for opinions is not directly bad, but perhaps wasteful, as it quickly leads to diminishing returns.

8. Sleep on it

When it comes to your own text, the most important opinion is your own. A good way to figure out what you really want and value is to write a text, put it away, and then return to it one or more days later and ask yourself if you still really agree with it.

Sender is responsible for delivery

Last but not least, remember it is the responsibility of the broadcaster to make sure the message was received. Don't assume people received and saw your message, or that they read it, or that they understood what they read. You need to put in the effort into preparing your message and following up on how it was received.

Writing well is also a way to show respect for the reader's intellect and time. Think about it this way: If you send a message to a hundred people and expect them to spend 6 minutes each reading it, you are spending 600 minutes (10 hours) of organizational time. If you spend 15 minutes extra to polish your message so it can be read and understood in just 2 minutes, you save the organization almost a full workday (600 minutes vs. 15 + 200 minutes equals 385 minutes or 6 ½ hours less).

It does not matter how good your idea is if the text describing it is bad. If you practice writing well, people near and far will become more receptive to your ideas.

What are your tips?

Are you a seasoned professional who masters written communication? What are your tips? Please comment below!