Menu

Subscribe

Becoming a Better Writer as a Software Engineer

Writing is an increasingly important skill for engineering leaders. Indeed, poor writing can hamper career progression, above a certain level. Tactics for more clear, more frequent and more confident writing.

I’ve observed that my writing is not up to par with my peers. How can I improve my professional writing, as someone working in tech?

I get this question from many people: senior engineers who realize they need to level up their writing if they are to grow to a staff position and engineering managers who feel they are not at the same level as their peers in expressing their expertise and thoughts.

This article covers:

  • The importance of writing for software engineers and engineering managers.
  • The process of writing well. Editing approaches to make your writing crisper and getting feedback on your writing.
  • Improving how you write. Observing and copying great writing. Habits to build your writing muscle.

This article was originally published in The Pragmatic Engineer Newsletter. Subscribe to get weekly issues.

The below article has recommendations for various paid products. As per my ethics policy, I have not been paid to recommend any of these, and no links are affiliate ones.

Why is writing important?

With remote work and distributed teams becoming more common, strong writing skills are a baseline for most engineering leadership positions. In fact, writing is becoming so important that companies like Amazon start their engineering manager screening process with a writing exercise, as I covered in the issue Hiring Engineering Managers. Other companies that have writing exercises during the interview process include Stripe – for Staff+ engineers – and TrueLayer, for principal engineers.

If you are a software engineer at a high-growth startup or Big Tech, the chances are you write more words per day than you write code. Everyday writing includes:

  • Commit summaries.
  • Code review comments.
  • Chat messages.
  • Emails.
  • Engineering planning documents.
  • Comments on proposals, Project Requirement Documents (PRDs) or engineering planning documents like RFCs.
  • Postmortems.
  • Performance reviews: peer reviews, self reviews and promotion documents.

If you’re an engineering manager, a tech lead or a staff engineer, then you’ll likely be writing even more of these:

  • Emails and chat messages.
  • Meeting agendas and meeting summaries.
  • Proposals for projects, headcounts.
  • Status update emails and documents for projects.
  • Presentations.

Crisp writing can help accelerate your professional career. As I wrote in the article Undervalued software engineering skills: writing well:

“It is at a larger organisation that writing becomes critical because messages reach a bigger audience. For software engineers, writing becomes the tool to reach, converse with and influence engineers and teams outside their immediate peer group.

Writing becomes essential to make thoughts, tradeoffs and decisions durable. Writing things down makes these thoughts available for a wide range of people to read. Things that should be made durable can include proposals and decisions, coding guidelines, best practices, learnings, runbooks, debugging guides, postmortems. Even code reviews.

For people to read what you write, it needs to be written well. If you grab people's attention early on, they will keep reading and receive the message you intend to get across. More of them will respond to it and do so with fewer misunderstandings of what you meant.

By writing well, you can scale your ability to communicate efficiently to multiple teams, to an organisation or across the whole company. And the ability to communicate and influence beyond your immediate team is the essential skill for engineers growing in seniority; from senior engineer to what organizations might call lead, principle, staff or distinguished engineer.”

The greater the influence of your position, the more people your writing will reach. In senior leadership positions, writing skills are yet more important. Engineering leaders who are also prolific writers include Andrew ‘Boz’ Bosworth the future CTO of Meta, Michael Lopp, formerly VP of Engineering at Slack, Will Larson, CTO of Calm and Steven Sinofsky, former head of Microsoft’s Windows division. As Steven Sinofsky writes in the article Writing is Thinking:

“Writing (and reading) really helps people if they are remote, if there is not a shared native language, or both. Writing can be difficult for some, for sure. That is why it is important to focus on the function, not the form. Don’t be afraid to help people (especially as a manager) through the process of the “basics” of writing.”

The Process of Writing Well

When you read a piece of well-written content, know that several steps happened behind the scenes:

  • Writing: a first draft was written. This draft captured most of the ideas and content seen in the final version.
  • Editing: the piece was edited for readability and ease of understanding.
  • Getting feedback: others might have given feedback, resulting in content changes and more editing.

Editing Approaches

When you write a first version of anything – from an unsent chat message all the way to a pages-long document – it’s in its draft stage. You have captured the content. However, to make the message as clear to readers as it is to you, the writer, you’ll probably want to edit it.

Re-reading your writing by putting yourself in the recipient’s shoes is the first step in editing. Before you send a chat message, re-read it, and imagine how the person on the other side will interpret it. Is the tone right? Are the contents accurate? Are you sharing the context?

Anything beyond a sentence or two will raise questions on the structure of your writing. How easy is it to follow? For longer writing, will your target audience have any incentive to read the whole text?

Common editing approaches for any writing longer than a few paragraphs are these:

1. Break it into readable chunks. Avoid an off-putting wall of text that will make most readers lose interest in reading it. Use paragraphs of a few sentences each, where each paragraph conveys one thought.

Take the medium you use into account. If you are writing emails that could be read on phones, consider making your paragraphs shorter, so one paragraph won’t take up the whole screen. If you are writing a Google Doc that most of your readers will view on their laptops, longer paragraphs are fine.

2. Remove unnecessary and distracting elements. The longer your writing, the more tiring it is for readers to process.

It’s no coincidence that companies with strong writing cultures like Amazon are strict in limiting all project proposals to a six-pager, often preferring one-page summaries. As I wrote about Amazon’s planning process in the article Preparing for the annual or biannual planning:

“Writing a relatively short planning document – where the length is capped at six pages – in practice often takes significantly more time than one that would not have a length limit. Because of the length limit, every paragraph is valuable. Those writing this document will put in lots of work to cut the unnecessary parts and make the content crisp and easy to read.”

While writing clearly takes effort, writing clearly and concisely is even more effort. As French philosopher and mathematician Blaise Pascal famously wrote in one of his letters:

“I would have written a shorter letter, but I did not have the time.”

Remove filler text that distracts from your message. For example, when writing emails, some people try to be polite by adding things like “[I probably don’t yet fully understand the thought process here and I apologize in advance but] could you please explain why…?” Practice polite, but to-the-point writing in these cases. You can often shorten your message without taking away from the tone and meaning.

3. Use shorter sentences. The longer a sentence, the harder it is to follow for your readers. Longer sentences can also become confusing as the clauses pile up. I recommend using Hemingway Editor to highlight parts that can be broken down.

Hemingway Editor helps detect hard-to-read sentences, overly complex phrases and adverbs that can be removed. The tool is free to use on the web, and is a one-off $20 fee for Mac or Windows as a desktop app.

4. Check grammar. Faulty grammar will leave the reader second-guessing and cause confusion. I use Grammarly, and it’s a tool I can strongly recommend, and one you could consider expensing at work – assuming you’ll use it day-to-day.

Grammarly improves grammatical correctness, writing clarity and keeping your writing engaging.

5. Use bullet points or numbering where they make sense. Bulleted lists are a good way to present several points. They can be used:

  • In emails, proposals, tickets: almost every form of writing you’ll be doing day-to-day.
  • To organize your thoughts. If the individual bullet points become too long, consider combining them in a paragraph.
  • To list related items in a way that’s easier for the reader to go through than writing paragraphs, just like this example of a bullet point list.

Numbering is another tool you can use in longer documents. This list of six editing techniques is an example where bullet points would not work well, as each point consists of multiple paragraphs. However, by using numbering, the reader can keep track of where we are.

6. Use bolding to make documents easy to scan. Use bold font sparingly so you can save this styling element for key thoughts, takeaways, or asks.

As an additional suggestion, avoid bolding inside sentences like I’ve just done. It’s harder for readers to scan things bolded inside a wall of text. Instead, re-structure your sentences so you can bold the first part of them.

You’ll notice my newsletter issues use bolding in varying quantities. This is a style I keep iterating on, with the goal of making each newsletter easy enough to scan and find relevant sections.

7. Use visuals, not just words. With technical documents, a screenshot or a diagram is often worth a thousand words. So use these in the documents you create.

For inspiration, see how Cloudflare explained the reasons behind the 2021 Facebook outage, with strong use of visuals. There is a picture for almost every paragraph of the text. Without these pictures, the summary would have been multiple times longer, and much harder to follow.

Excerpt from a well-written Cloudflare postmortem, which is easy to follow thanks to the good use of images.

8. Value the reader’s time more than your own. The reason for editing your writing is to make it easier for others to digest your thoughts.

If you’re sending a direct message to one person, a quick scan of what you typed should be enough. If the same message is going out to a group chat of 100 people, take a little time to edit it for clarity. And if we’re talking about a document read by many people in an organization, then put in the time to make it easier for all those people to read it.

As former Amazon engineer Curtis Einsmann shares:

Get Feedback

After editing your writing, you might think it’s clear and crisp. But will readers agree with your assessment?

Ask for feedback from colleagues on emails, documents and other writing for which you could use another pair of eyes. A good approach is to share what you wrote in another collaborative editor like Google Docs or similar.

Example of comments and suggestions using Google Docs. Collaborative editing tools with commenting and suggestion features are excellent ways to get feedback asynchronously.

Ask people directed questions when sharing your writing. Most people will be unsure what feedback you’re looking for, if you just ask for generic feedback. Ask specific questions that narrow down what help you need. Prompts you could consider include:

  • “How easy to read did you find this? What is one improvement you’d suggest?”
  • “What resonated the most? And what part did you find redundant?”
  • “What would you suggest to make the takeaways more clear?”
  • “What part of this document was the most confusing?”

Consider jumping on a call with your manager when writing an important document. As VP Financial Engineering Chris Henson suggests:

You might be worried that you’ll annoy your colleagues or manager by asking too frequently for feedback on your writing. But in my opinion, almost everyone seeks too little feedback.

Just like there’s rarely a problem with wanting to do pair programming frequently, there’s little harm in asking for feedback on what you write. Make notes of suggestions, and apply those suggestions to your writing next time.

Hiring an editor is the most expensive way to get feedback, though it can be a high-quality way to do so. The first time I hired an editor was for my first book, The Tech Resume Inside Out. I have since worked with editors for all my books.

As hiring an editor is an investment, most people save it for writing that goes out to larger audiences. If you are writing a press release or content that will be published externally, you might be able to justify hiring a copyeditor. If you have the option, I’d suggest going for it.

There might already be editors or technical writers at your workplace. If your organization publishes an engineering blog, there’s a fair chance they hire copyeditors to review these articles. If this is the case, commit to writing an external-facing post, and ask for editing by one of the in-house or contract professionals.

There are ways to get professional editing for free: write an article for a publication that provides this editing. This includes writing for publications listed in Who Pays Technical Writers. Some of these titles not only pay a few hundred dollars for an article, but they often provide copyediting.

Relying on automated writing tools for feedback can dramatically improve the readability of your writing. This is true for both Hemingway Editor and Grammarly, as well as others.

However, these tools will occasionally give suggestions that are either incorrect, or don’t fit your style. Don’t accept suggestions you disagree with, or ones you feel leave your writing in a worse state.

The more confident you become with your style, the more suggestions you will ignore which the tool makes. In my case, I have learned which suggestions and rules to always ignore, which ones to consider based on the context, and which ones to accept and incorporate into my writing.

Improving How You Write

There are several ways to improve your writing skills. Let’s go through them.

Observe and Copy Great Writing

What does great writing look like? Chances are, you already know. But have you paid conscious attention to it? Here are ways to be more deliberate in observing, saving and copying the ingredients of great writing.

Read fiction and find books you cannot put down, which you read every sentence of. Then revisit those books and analyse their style. How are sentences written? What made you want to read more and not skip ahead?

People pick up nonfiction writing because they want to learn something. It’s because of this that nonfiction that is written poorly might still become popular.

However, fiction needs to draw people in to read more. Good fiction uses a variety of techniques, including storytelling style, varying the length and rhythm of sentences and paragraphs, and many other elements.

But reading fiction won’t make you a better writer by itself. However, finding great fiction will expose you to great writing which you willingly consume. I still frequently end my day picking up a novel, reading for up to an hour before bed.

Find and save some of the best professional writing you come across at work and outside work. Collect a few of the best-written examples of:

  • Emails:
  • Project status reports.
  • Project launch announcements.
  • Welcoming a new joiner.
  • Organization-wide announcements.
  • End-of-year summary.
  • Engineering planning documents or proposals that are informative. Look for not just great writing, but great use of diagrams.
  • Postmortems that are to the point.
  • Product specifications like PRDs or other product planning documents that are easy to understand.
  • Tickets defining work well.
  • Discussion threads that are concise and to the point.

Analyze these written artifacts. What characteristics made them good to read?

Use some of these artifacts as templates to copy from the next time you write something similar. For example, if you plan to put together an engineering proposal, copy the style of the proposal that resonated most with you. After you write your document, compare it with the inspiring one and aim to make yours equally clear as it.

Build Writing Habits

We’ve covered the theory of improving your professional writing. However, the only meaningful way to improve is to put all of the above into practice, then rinse and repeat.

Teach yourself touch typing if you do not yet type without looking. Until typing on the keyboard is seamless, you’ll likely write less and slower, than when you can type without looking at the keys, and do it fast enough to not break your stream of thought. You can find countless courses online that help master this technique.

Put writing habits in place. Repeat activities where you make time for editing and getting feedback. These are efficient ways to improve your writing with deliberate practice. You’ll also want to create the habit of observing great writing, and feed these observations back to your own improvement process.

Define writing activities where you commit to editing and seeking feedback. You write a lot throughout the day, and it’s not realistic to add the overhead of an involved editing and feedback-seeking process to every document. However, you should define which existing or new writing activities, you’ll pay more attention to.

For example, if you already create lots of long-form writing during your day job, define the most important and most widely-circulated of it. Commit to spending more time editing these documents and ask your manager or a peer for feedback.

Below are writing activities that are ideal for following a more involved editing and feedback process:

  • Start writing weekly 5-15 updates. Spend 15 minutes at the end of each week on a report that can be read in five minutes. Send this out to your manager and a few peers at work. This exercise is an excellent one to do for anyone in an engineering leadership position; I used it with great success. In reality, it will likely take more than 15 minutes to write and edit this report, but over time you’ll get better at it.
  • A weekly project summary to stakeholders. Are you leading a project at work? If so, start to put together a crisp summary of the overall progress, the risks, and what happened since the last update. Make this update easy to read and take inspiration from the best project update emails and documents you see in the organization. Subscribers have access to a 🔒Project reporting example to use as inspiration.
  • Volunteer to take notes at meetings and send out summaries. Taking notes, then spending additional time writing up a crisp summary of decisions made in a meeting, might seem like a thankless task. True, it is time-consuming for you, but it can save time for many others, on top of helping you get better at summarizing.
  • Initiative proposals. Do you have an idea for a project you or the team should do? Write up the idea, the problem it solves, the impact, and your ask. Edit it, and ask for feedback to make it more clear, then send it out to the relevant group, asking for comments. A well-written proposal is more likely to get the feedback it needs to succeed, than one that people stop reading midway.
  • Design documents. Take time editing and getting feedback on design and planning documents you write. Use visuals to convey information more clearly. Collect great design documents and copy structures that work for them. Ask about tools others used to create easy-to-understand diagrams and images. Tools I recommend using for technical visualization are Excalidraw, Lucidchart and Miro.
  • Documentation. For documentation you expect more than one person to read, follow similar advice to when writing design documents.

Continue Learning

Below are high-quality resources that can help you become a better writer.

Note that none of the below links are affiliate links or sponsored ones. See my ethics statement on the lack of such links.

Free online resources

Books

  • On Writing Well by William Zinsser. The classic guide to writing nonfiction. The book that helped me write more concisely.
  • Dreyer’s English by Benjamin Dreyer. An entertaining book to make you a better writer.
  • The Elements of Style by William Strunk Jr and E.B. White. A succinct book to help eliminate clumsy and incorrect use of English.

Courses

  • There is an ever-growing collection of paid writing courses which aim to help improve writing via practice and feedback. I don’t have first-hand experience with these: do your own research on them.

Tools

Takeaways

Writing becomes more important as you grow more senior, regardless of where you work within tech. For many people, their lack of writing skill becomes a blocker to progress beyond certain levels.

This issue was a summary of systemic approaches you can take to improve your writing skills:

  • Edit your drafts before you publish them.
  • Get feedback and iterate on some of your writing.
  • Observe what great writing looks like, and copy elements that make it pleasant to read.
  • Put habits in place so you work on your writing muscle on a regular basis - at the very least, weekly.
  • Continue educating yourself about writing better through resources – books and courses – dedicated to this topic.

This issue is packed with advice that is only worth something if you take action on it. I suggest you make a plan on how you will improve your writing. Subscribers have access to a 🔒Writing goals and accountability document to do so.

Technical skills combined with writing skills are a superpower in a world that is increasingly writing-heavy. Writing skill takes time to build and the best time to start doing so is now. Good luck on your writing journey!

Thanks to Zsombor for reviewing this article.

Subscribe to my weekly newsletter to get articles like this in your inbox. It's a pretty good read - and the #1 tech newsletter on Substack.