Software engineering's most undervalued skill

As a company scales, the ability to communicate effectively becomes more important than the ability to write code. Your time, your manager's time, and your peers' time are scarce resources. So if you want your peers to actually read that Confluence page of yours, you have to write it 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 do 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: Edit harshly

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.

Most engineers think the job is done once the information is on the page, but that's actually where the real work begins.

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

Lesson 2: Write like you speak

This is debatable depending on your audience, but in spaces where authenticity is valued, corporate-speak is 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 words we use when we're trying 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: Use the "inverted pyramid"

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

We need to flip this habit on its head.

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

Lesson 4: Formatting is critical

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: People hate AI slop

The easiest way to lose your audience is to let an LLM write for you. We've all seen the signs: Title Case Everywhere and the "eager-to-please" tone.

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?".

Lesson 6: Read more books

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 which helped me become a better writer:

• 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 make it something succinct, enjoyable to read, and uniquely yours.

You need to accept that your first draft is going to suck. You need to accept that you'll look back on what you wrote six months from now 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 has shifted and evolved.

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

Good luck, and have fun!