返回资讯中心
外部精选
软件工程
#开发者实时流

Becoming a Better Writer (2022)

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

Hacker News 最新rzk2026/10/31 · 17 天前30 分钟阅读

以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。

Translate

Becoming a Better Writer

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

Gergely Orosz

Jan 18, 2022

200

8

7

Share

The following was a paid article until Oct 2026, when I made it free. Engineers writing about their own experiences and learnings is great for our industry, I just see less of this happening, at least without AI. I hope this article is helpful with tactics and examples.

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, engineering managers who feel they are not at the same level as their peers in expressing their expertise and thoughts, and even product managers who feel they write less efficiently than they want to.

The importance of writing for software engineers, engineering managers, and executives.

Editing approaches to make your writing crisper.

Continuous learning: books, and tools to boost your writing.

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.

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:

Comments on proposals, Project Requirement Documents (PRDs) or engineering planning documents.

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:

Status update emails and documents for projects.

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.”

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.

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.

  1. 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.

  1. 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.

  1. Check grammar. Faulty grammar will leave the reader second-guessing and cause confusion. I use Grammarly (I pay for it), and it’s a tool I can 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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:

Curtis Einsmann@curtiseinsmann

@GergelyOrosz 3 writing tips that have worked for me:

  • Simplify the language
  • Start with “why” then “how” then “what”
  • Value the reader’s time more than your own

5:44 PM · Jan 12, 2022

1 Repost · 11 Likes

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 do

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →