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!
Top comments (8)
The 7th and 8th tip was so valuable for me when I was wrote my first article. My patience was challenged but oh, I'm so proud of my work!
This post provides insightful tips for enhancing written communication skills in the software industry. It emphasizes the importance of concise, fact-based writing and offers practical advice on structuring and presenting information effectively. As a software professional myself, I appreciate the emphasis on clarity and brevity, which are essential in conveying complex technical concepts to diverse audiences.
I like the first tip. It is better to explain things in a few lines instead of sending an essay-size message😄. Thanks for sharing
There is a corollary point though: avoid jargon, even if it makes the text shorter... my personal approach is always to use the unabbreviated form of things I wish to shorten followed by the abbreviation (or acronym, if it's pronounceable as a word) in parentheses, for example:
Domain Name System (DNS).
great post. thank you! My favourite is Sleep on it but I cannot do it.
Thanks for sharing
I like your article. The point you make about saving everybody time with a polished text is well worth remembering.
These are great tips. I completely agree with the first, fifth and last tips. Thank you for sharing.