From Code to Words: How to Write Well for Software Engineers
How clear writing boosts alignment, saves time, and elevates your impact.
In this guest post,
, the Staff Software Engineer at Meta behind the newsletter, dives into why writing is essential for engineers and how it can be a game-changer for aligning teams, saving time, and driving outcomesSidwyn shares actionable advice on mastering the art of writing through a simple yet powerful framework: the three 'I's—Identify, Iterate, and Invite.
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:
Who am I writing for? Every audience has different needs. Are you writing for:
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.
Product managers? Highlight user impact, trade-offs, and timelines.
Executives? Keep it high-level: the “why” and the ROI.
A combination of the above? You'll likely have to generalize and link to specific docs for engineers and PMs.
What does my audience need to know?
Define your core message: If they can only remember one takeaway from your article, highlight that one thing.
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
Writing a document is like debugging code — it rarely works perfectly the first time. Multiple drafts help strengthen your piece. I usually have up to three drafts per document that I write.
When revising drafts, I take the opportunity to:
Structure my thoughts clearly:
I use headings, subheadings, and bullet points to organize ideas. (Just like this piece!)
Bonus: I like to include a TLDR at the top or bottom of the document for people who don't have time to skim it. This helps them understand the document at a glance.
Be concise: Remove fluff. Focus on what matters. Always ask yourself, “Can I say this in fewer words?” If your company allows, use tools like Grammarly or Hemingway. These help make your writing even more succinct.
❌"In order to ensure that this feature is implemented correctly, we must first take the necessary steps to gather requirements."
✅"We must gather requirements to implement this feature correctly.”
It is also essential to ensure that drafts don’t slow you down. You’ll want to set a limit on them (e.g., three drafts) so you don’t continuously revise your writing.
As you write each draft, there’s one last crucial step to tighten your writing.
3. Invite Others to Provide Feedback
I've always found that good writing is collaborative – it's not a one-person effort.
I enjoy sharing early drafts to receive feedback. This feedback is beneficial since (1) your perspective might not match your audience’s understanding, and (2) feedback catches gaps, misunderstandings, and assumptions.
To invite others to provide feedback,
Share drafts early: Let your team weigh in on structure and content.
Be specific in your ask:
“Does this section clarify the trade-offs?”
“Did I hit the right topics with this document? What am I missing?”
Example: I shared this draft with Fran a week before it was published, incorporated his feedback, and revised it to the current version.
TLDR
Writing well isn’t just a skill; it’s a process. Remember the three 'I's:
Identify your audience: You want to know who you're writing for so you can tailor your message for clarity and relevance.
Iterate on drafts: Use drafts to help refine your thoughts and polish your ideas.
Invite feedback: Leverage your teammates to provide feedback and improve your drafts.
That's it! I hope this helps you improve your writing. If you are interested in learning more, I share my journey of leveling up as a Staff engineer at Meta over at Path to Staff.
👏 Weekly applause
Some articles I enjoyed reading during the week!
How Public Speaking Accelerates Your Engineering Career by
and . This is an article I wrote in Sidwyn’s newsletter about public speaking!How did I improve my focus & productivity with a simple Second Brain in Notion? by
. As a productivity nerd, I liked this one about using Notion! I think capturing and organizing information will become more and more relevant with LLMs. This goes aligned with next article in this listWhy Retrieval-Augmented Generation (RAG) is Essential for Trusting LLMs by
 | A guest post by
|
This was great, Fran and Sidwyn, and the best part is that it works! :) Once, I had to ghostwrite emails for a different freelancing team because their client was frustrated with their reporting style. This almost cost them the contract! 🥶 It’s super important to keep in mind who you write for, and if you stop there, you have already achieved a lot.
Thanks for the opportunity Francisco. I'll be in the comments if anyone has questions.