From Code to Words: How to Write Well for Software Engineers

How clear writing boosts alignment, saves time, and elevates your impact.

Get the free AI Agent Building Blocks ebook when you subscribe:

---

In this guest post, Sidwyn Koh, the Staff Software Engineer at Meta behind the Path to Staff Engineer newsletter, dives into why writing is essential for engineers and how it can be a game-changer for aligning teams, saving time, and driving outcomes

Sidwyn shares actionable advice on mastering the art of writing through a simple yet powerful framework: the three 'I's—Identify, Iterate, and Invite.

Template attribution: presentationgo.com

I’ll let Sidwyn take over from here!

---

Have you ever found it hard to align on a decision? Or stuck in an endless debate?

We build systems, solve problems, and write clean code as software engineers.

But there's another kind of "writing" that’s equally important to our success — effective communication through writing documents.

Writing well is a skill that engineers should master to succeed, whether crafting documentation or drafting project proposals.

Why write well

I once spent several hours discussing a new service architecture with three other engineers. As we all had different opinions on implementing it, it wasn’t fun. All four engineers soon realized it wasn't productive and were going about in circles.

I took ownership, cobbled together a one-page summary of everyone's thoughts, and had everyone sign off. This one-pager turned a discussion that could have been three weeks into one hour. We met once again to talk over the one-pager and were aligned in the next 15 minutes.

Writing is essential and has clear benefits for us engineers:

• Aligns everyone on the same page: A well-written document becomes your team's “single source of truth.” You can look back and rely on this artifact whenever necessary.

• Saves time: Writing allows teams to collaborate effectively without scheduling multiple meetings. If a decision can be clearly explained over writing vs speaking, then skip the meeting.

How to Write Well

As hard as writing can be, I often emphasize that writing well isn’t a talent — it’s a skill you can develop with practice.

To keep things simple, here are three 'I's to remember when writing: Identify, Iterate, and Invite.

1. Identify Your Audience

When beginning a draft, I like to ask myself two questions:

1. Who am I writing for? Every audience has different needs. Are you writing for:

   1. Engineers? Focus on technical precision and implementation details. Make sure your designs are complete and detailed.

      • Side note: engineers love bullet points, which is how most of this essay is formatted.

   2. Product managers? Highlight user impact, trade-offs, and timelines.

   3. Executives? Keep it high-level: the “why” and the ROI.

   4. A combination of the above? You'll likely have to generalize and link to specific docs for engineers and PMs.

2. What does my audience need to know?

   1. Define your core message: If they can only remember one takeaway from your article, highlight that one thing.

   2. Ensure my writing is coherent: Continually reinforce my message across multiple sections to drive home the message even further.

Lastly, I put myself in my audience’s shoes and continuously proofread my writing as I finish paragraphs. This makes sure that I answer the above two questions: 1) my audience will understand my writing, and 2) my writing is coherent and flows well.

Once I have what I think is a solid structure, my first draft is complete.

2. Iterate on Drafts