Software engineering's most undervalued skill

As you progress in your software engineering career, your ability to communicate effectively becomes even more valuable than your coding skills. Time is a limited resource—for you, your manager, and your peers. If you want your colleagues to actually read your Confluence pages, you need to write them well.

Writing is, by far, software engineering's most undervalued skill.

Many engineers despise writing because it takes time away from the one thing they actually want to write: code. In reality, writing is the highest leverage tool an engineer has in her toolbox.

Here are six things you can do today to improve your writing.

Lesson 1: Ruthlessly edit your writing

Never use two words when one will do. — Thomas Jefferson

The first draft of anything you write is just for you; the second draft is for the reader.

Many engineers believe that once the information is on the page, their job is done. In reality, that's when the real work begins.

Go back through your text and challenge yourself to delete 20% of it. Remove the "I think that"s, the "actually"s, and the "just"s. If a sentence doesn't offer new information or a necessary clarification, think: do you really need it? People don't read Confluence pages; they scan them. Give your readers less to scan.

Lesson 2: Write the way you speak

This is debatable depending on your audience, but in spaces where authenticity is valued, corporate jargon can be a barrier to trust. If you wouldn't say, "Henceforth! We shall endeavour to leverage this synergy!" in person, don't write it in a document.

Avoid "therefore", "utilise", and, for the love of all things holy, "I'm thrilled to announce". These are filler phrases we use to sound professional. Instead, use "so", "use", and "I'm happy". Simple language isn't "dumbed down"; it's more accessible and more efficient.

Lesson 3: Write for the reader

Good writing starts with empathy for your reader.

Focus on what they need to know, not just what you want to say.

In journalism, the most important news comes first. In engineering, we often do the opposite: we document the entire history of a bug before mentioning the fix at the bottom.

Reverse this habit: lead with what matters most.

Put your conclusion, ask, or the tl;dr at the very top. If your manager has only 30 seconds before their next meeting, what's the single point they must take away? Tell them that first, then provide the context and "how-we-got-here" details below for those who want to dig deeper.

Lesson 4: Format for readability

A wall of text is a psychological deterrent. You can improve your writing without changing a single word, with formatting alone:

• Use bullet points for lists or sequences.
• Bold key phrases so skimmers catch the main point.
• Use headers to break up different sections.
• Keep paragraphs short. Three sentences is usually enough.

Lesson 5: Avoid AI-generated slop

Letting an LLM write for you is the fastest way to lose your audience.

When you write something that is clearly AI-generated, you send a subtle signal to your readers: "I didn't think this was worth my time to write, so why should it be worth your time to read?".

Instead, use AI as a sparring partner. Write your first draft first, to get your thoughts down on paper in your own voice. And rather than asking AI to "rewrite this", ask it for specific feedback instead, like "where can I change passive voice to active voice instead?". Ask how to make sentences clearer or where your argument is weak, rather than handing over the whole job.

Make sure your final draft sounds like you, and only you.

Lesson 6: Your writing reflects what you read

Like LLMs, you can't create high-quality output without high-quality input. Reading is the only way to build an intuitive "ear" for good writing. Through reading, you can begin to transform abstract advice into a natural writing instinct.

Here are two excellent resources that helped me improve my own writing:

• George Orwell's Six Rules for Writing
• 100 Ways to Improve Your Writing by Gary Provost

Summary

Writing is hard. AI may have helped us exponentially shart more words on a page, but it's still up to you to shape those words into something clear, engaging, and uniquely your voice.

Accept that your first draft is going to suck. Six months from now, guaranteed you'll look back at what you wrote and cringe. Hell, I'm probably reading back on this post years from now with cringe (edit: yep, hello from the future!). But all of that's a good thing! It means your thoughts, ideas, intuition, and sense of what "good" writing means to you have shifted and evolved.

Practice is what helps you develop your own writing voice. You'll find, in time, that you become even more connected to the "rhythm" of your own writing. The good news is that it only gets easier and more enjoyable the more you write.

Good luck, and enjoy the process!