Improving your writing

Published: 18 February, 2024, updated: 18 February, 2024

Despite nuking my previous writing on the Internet back in 2011 and only getting back to it in 2024¹, I’ve been doing a ton of writing at work². While some of it is the standard fair of personal engineering writing - RFCs, project lifecycle posts, and so forth - I’ve also been roped in to draft and/or review large-scale (in a few instances, company-wide) organizational communications, as well as maintain a “personal blog” in the form of a Workplace group.

One of the more frequently asked questions³ I get is how to get better at writing⁴.

There’s an obvious, straight-line, answer here - read some style guides or books on how to write well (ie, study) and write more (ie, practice). The people who asked those questions probably thought about those, so clearly they’re looking for a different sort of advice.

Form opinions - you’ll need them

All through the writing process - whether preparation, writing, editing, or review - you need to use a sense of what “good” looks like to drive you forward. What “good” entails is contextual: there are different types of communications, in different types of contexts, to different types of people.

Sure, read some style guides and books⁵, but that’s just the start. You need to read each of the different types of communications, develop an understanding of the contexts relevant to your writing, and know who your specific audience is.

You’re often on the receiving end of these communications, and it is valuable to evaluate what you feel about those communications, and untangle what about it you liked and didn’t. Was it clear you were supposed to take away? Was it too long? Did it mention things you didn’t know about? Was it a waste of your time? Do whatever it is you do to retain these thoughts somewhere - write it down somewhere, perhaps, like I often do, with no expectation to ever read it.

Theory of Mind

After you’re familiar with being critical of communications you receive based on how you feel about them, the next step is to try model what other people might feel about them.

You may not like a particular email because you already knew about the issue, it was too high level, and it spent a long time discussing what we’d do in 3 months, rather than what to do next. But are you actually the main audience for this email? Who is the main audience? What is it that they care about? Did they know about the issue? Do they want the low-level details and the immediate next steps? What do they want to hear about?

As you go through the writing process, knowing what type of thing you’re writing, who you’re writing for, what they need to know, what their current mindset is, and what “good” looks like should lead you to a decent result.

Before you start writing:

Develop a plan and stay focused

While some write exclusively for the writing, most writing aims to change something for the reader. We want them to understand something, do something, or maybe feel something.

Defining your primary audience and the primary thing you want them to take away is the core of the plan you should be making while writing. Mostly I do this in my head, but especially when collaborating with others in drafting some wider communication or when stakes are higher, it’s often valuable being very explicit about this.

Once we have a defined audience, we can use what we know about the audience to help them get from where they are to where we’d like them to be - the steps of the argument or explanation, as well as pitfalls (unforced errors) in how we communicate.

Primary goal

This is perhaps the biggest determining factor of how effective your communication will be. If you don’t know what you want, you’re unlikely to end up writing something to achieve it.

Think about what you want to be true in the future. If you can’t achieve that in one go (the most common case), think about what needs to be true before your end goal can be true. Iterate until you have some clear objectives you’re trying to achieve in your writing.

Not every piece of writing is going to change the world.

Usually what you’re doing is actually fairly small - maybe even subtle. Sometimes your goal might be to plant the seeds of some larger project in people’s heads. It might be to write a proposed plan just so that there’s a written plan to be reviewed. Sometimes it’s to write up what you know so that others can correct you. Sometimes it is to correct a particular misconception among a group of people.

While diving into the deep end and writing the sorts of things that change the direction of companies is possibly one way to do things - especially at a startup. But you can also get your practice in on the lower-stakes, more menial, and more frequent opportunities in the project or team lifecycle.

There’ll always be some secondary goals in your writing - things like “make it clear this project doesn’t need additional scrutiny” or “prove I’ve got a handle on things” or maybe even “provide some evidence to use in my performance review”. That’s fine - just make sure that these don’t detract from the primary goal. (And if you’re ever writing something just for performance review points, please don’t post it anywhere I have to see it.)

Primary audience

It’s easy to be a bit flippant about defining the primary audience. “Anyone who reads it” could be a valid audience in some rare cases, but usually you want to be more specific. You could bring your specific knowledge about specific people you know in your audience, like “Bob in Accounting”, but unless it’s literally for just them, you’ll want to think about the more generic audience.

Example audiences:

• All engineering individual contributors at Meta
• All engineering managers in the Traffic org
• The set of engineers in the org that perform good design reviews
• Direct contributors on the Zed Project
• Zed Project extended stakeholders
• The people in the future reading this diff / Pull Request
• My reporting chain (upwards or downwards)
• Future me

Think about what you’d like to see happen from what you’re writing, and who the people are that would be involved in that. Whenever there’s a subset of a general group that won’t be taking action, consider being more specific - even if it means creating two or more audience sets.

For each audience you’ve identified, consider what they currently likely know, and what you’d need to tell them to take the action that you want from them.

Look over what you’d need to tell all audiences, and find how much overlap there is between the audiences. If there’s an audience that needs dramatically different information than the others, consider writing a different communication for them - which may need to be scheduled before or after the thing you’re currently thinking of writing.

Talking points

Often when you’re doing some writing, there’s some set of people who have opinions about what should be in that writing. I’m not talking about the audience who expect to see a particular thing, but rather stakeholders who think your audience should see particular things. This can often be useful - they’re often aware of things that you aren’t, and their guidance will help you get what you want out of the writing. But sometimes it isn’t - and you’ll need a different set of skills to work with that.

These “talking points” are good to write down. They’re a checklist of things you should be including in the content.

There are also a set of things you want to avoid - things that if mentioned will confuse people, even if the mention is to try avoid confusion. There may be something you’d like to include, but can’t for some reason. These are also a checklist that can help you evaluate your work, so writing them down is good too.

There may also be relevant communication or documentation you want to be sure to include - add that to your checklist.

Outline

Some will suggest that the “Tell them what you’re going to tell them, tell them, then tell them what you told them” strategy is the be-all and end-all of business communication. Every piece of writing should start by stating the (usually three) things you’re going to write about in the introduction, then explain those three things and why they’re the three things in the body, and then re-state those three things in the conclusion.

It’s okay. You should try it. At the very least, consider the classic introduction, body, and conclusion triumvirate fairly rigidly.

There’s also the “tl;dr” - an incredibly compressed description that can help people determine if there’s something they need to do and/or whether it’s worth their while to read more. Since we’ve already done the work above to determine what we want and who we’re talking to, this is usually a great test. When I’m lazy and get around to the “tl;dr” and struggle, I know it’s because I’ve been winging it too much.

(I’ve seen documents where the same 3 things are now mentioned 4 times - once in a “tl;dr”, once in an introduction, once in the body, and once in the conclusion. Don’t do that.)

Focus

Increasingly over the last decade or so, what you write is in a firehose that others are drinking from, and so terseness and focus are often invaluable. That’s not to say that bite-sized content is absolutely critical in all writing⁶, but waffling on is usually something to be avoided⁷, and including things that are wholesale not necessary or in service of the goal of your writing won’t earn you many fans.

Finding the fewest possible words to express what you want others to know, without risk of confusion, has always been a key writing skill, and its value has increased in step with the flow of the firehose. Reducing words-per-sentence through replacing “due to the fact that” with “because” isn’t nearly as effective as wholesale removing sentences, paragraphs, or even sections⁸ - so maintain focus on what you’re trying to convey.

While coming up with the shortest way to express what you want to share is one of the hardest parts of writing, at least some of that time will be reclaimed as we enter the next phase – editing and review.

Editing and review separates “drafting” from “writing”

Its altogether too easy to think that the hard part of the writing process is in the drafting stage - the bit where you have enough of an idea of what you want to write that you can write something down. It’s often the stage people struggle with as they’re writing - possibly because they’re not actually at that stage.

None of the people I’ve met whose writing I enjoy just “poop” out something excellent in one go – starting their writing on the introduction and finishing as they hit the conclusion.

Iterative process

Get used to the idea that feeling like you have the first version of something is just a milestone on the journey. You rarely get to something succinct literally by removing or modifying phrases or words from what you’ve written - it’s usually through larger-scale restructuring and rewriting.

For the most important parts of the most important things I write, I generally write them at least twice, and usually three times.

The first time I write something will be a “straight through” version of a particular section⁹. Once the section is complete, I’ll quickly read it back and do basic editing and reordering. This is where I’ll probably write alternatives for things like introductions and conclusions. I don’t keep any telemetry for this, but my guess is somewhere between a third and two-thirds of the time I’ll end up using the alternative as a base.

Once I have the larger document in hand, I’ll read everything again, and perform some mix of small word/phrase edits, reordering of sentences/paragraphs, striking through things that need to be rewritten, and leaving notes. It’s often at this stage that I’ll feel the need to rewrite the introduction and conclusion.

Getting to “final draft” + collaborators

For less important documents, this’ll be when I post them. For more important documents that I’m writing entirely by myself, this will be when I take a break from them.

For others, this is where I’ll start sharing the draft with others. Sometimes I’m writing as a representative of a group of people, and I’ll want to make sure that group gets to give feedback. In some cases, I’m a shadow writer for someone - they definitely want to see it, but more often they’ll have people for that, who will review the content not only for message but also for voice. And sometimes I’m writing for myself, but I would like some feedback from others.

No matter the reason for the review, this has been a treasure trove of writing lessons for me. As the propaganda posters strewn over Meta offices state: “Feedback is a gift”. If someone tells you they’re confused about what you’ve written, you have something to try improve right there. Sometimes they’ll even suggest alternative ways to phrase things. They’ll propose deleting entire paragraphs because they’re not needed. And they’ll often be right!

I recommend trying to help review and edit others’ writings whenever you have the opportunity as well. It will get you used to entering the mindset of a reviewer and editor of writing. You’ll be able to practice trying to model the audience of the writing and figuring out how they might receive it. You’ll be less attached to the writing since you’re not the author, but also need to “leave good enough alone” since you don’t want to annoy the author. All of these will help when you’re trying to review and edit your own work.

Pressing the publish button

While there’s an entire world of writing exclusively for oneself, most writing is aimed at others reading it. Which means you need to publish it at some point. This is where you’re exposing your work to others. For most people, this is intimidating - what if they don’t like it?

You can learn a lot about yourself in terms of how you deal with this. For example, are you more concerned about what others think of you than the value of the thing you’re writing? Are you more concerned about what people think of you when you’ve done something than when you haven’t? What would it take for you to feel comfortable with publishing something?

Overcoming this final exposure to the world step likely has entire books written about it, so I’ll focus on one piece of advice. Start by figuring out what you’re fairly sure you would be comfortable sharing, and write that. Get through the cycle of writing and publishing, even if what you’re writing aren’t the masterpieces or hot takes you’d eventually like to get to. If perfection is your problem, start on the smallest thing you can.

As you go through this cycle, you’ll likely get some feedback from it, and quite likely you’ll be more confident to take on what you want, know better what you want to write about, and/or discover that people are quite forgiving and kind when you inevitably make some mistakes.

Sidetrack: The venue

One thing to consider in your communications plans is where to publish things. There’s an unfortunate perception that one should maximize “visibility” by making posts in the biggest possible forum - both for the thing you wrote and for yourself. Self-promotion is an entirely separate topic¹⁰, but I think the answer for where to publish is at least a bit more clear.

Every organization or person will have different avenues for communication. For my writing I may post it here or on my technical blog or in my Workplace group at work based on the topic or audience. At Meta, we have Workplace groups for most projects (and sometimes even features/sub-projects within those projects), and for teams and “orgs”¹¹. There’ll even be inter-team/org groups for facilitating communication between them.

As a rule of thumb, you can take your “primary audience” of your writing and look for the smallest forum that covers almost all of them¹², and for which simultaneously most people who receive your message will consider it valuable. For anyone not in that forum, you can either tag them if it is an open forum (or send them an email or chat message), or you can send them the whole thing if it is not.

Moving on

You likely won’t immediately stop thinking about what you’ve written, but you definitely need to move on from it over time.

Post-publication

Don’t worry if you feel the need to reread what you wrote, multiple times. Don’t worry if you discover all sorts of silly mistakes while you’re doing this - spelling errors, missing words, doubled words, or entirely inverting the meaning of crucial parts of your argument. There’s just something about reading it when you know others can¹³ that brings these things out despite all your efforts in the past.

With a lot of writing, there’s some expectation of engagement from those that read it, and this will likely follow an engagement probably curve measured in ~days. During this time, remember to be available to respond, and remember to respond to everything.

Importantly, for RFCs and proposals, actually make changes based on feedback. Don’t just “Yeah, that’s a good point” in the comments and then not change anything. Add things to the trade-offs, at least. Document the alternative and why it wasn’t chosen. Follow up with the stakeholders who were identified as important. These types of documents aren’t write-once, and they’re not publish-only - they come with a contract to integrate feedback.

Distance and reflection

Once engagement has died down, you’ll probably forget about what you wrote, but there’s one last piece of lifecycle left - reflection. After sufficient distance from the writing, with a fresh and more objective perspective, you should examine what you wrote and consider what you could have done better. Consider the engagement you got (or didn’t) and what you might have done to bring better clarity to avoid now-obvious questions, what standard you might want to hold yourself before making proposals or publishing, who you might have best got early feedback from, and so forth.

When you’re writing something - as you plan what you’re doing, forming an outline, writing, and editing - you’re developing experience in the detail: structure, cadence, word choices and vocabulary, modeling the reader, and so forth. Think of this as exploring for the “local minimum” - getting better without fundamentally relocating yourself. The feedback from those who read what you wrote is how to take those bigger steps¹⁴.

Sidetrack: The treadmill

There’s a treadmill people can get on with publishing something and seeing numbers going up over time or people engaging with it. You can get excited by being shared to Hacker News or some subreddit or getting upvotes on various platforms, comments, shares, views, and so forth. Be careful here - it’s easy to start getting used to this, shifting how you see yourself, shifting your goals, starting to expect a level of engagement, and so forth. Opening up your apps and refreshing a few times an hour in case the notifications got lost.

If you suspect this is something you want to avoid, or something you think is happening to you, take some precautions. The prevailing wisdom is adding tracking to your site¹⁵, set up a bunch of searches and/or use services that notify you when you’re mentioned, and so forth. If you want to grow an audience, they tell you, this is the only way. There’s a freedom that comes from not having to consistently satisfy an audience - consider whether you want to give that up. Just like the ratings/promotion treadmill in tech, you don’t have to get/stay on it if you don’t want to¹⁶.

Ignore all the advice, including mine

The obvious meme here is that beginner and more tenured writers often basically end up doing the same thing - largely just writing whatever is in their brain. You pay your dues in the middle by spending more time being deliberate about form, structure, audience, and so forth.

And then you slowly stop doing it quite so deliberately, at least not every time, as it both becomes ingrained in how you do things and also because you might even start to subvert these established patterns. Great writers (certainly not me) are sometimes essentially creating and shaping their own audiences, sometimes coming up with their own structure that appears entirely unstructured to others, and often go on long meandering journeys rather than staying “focused”¹⁷.

For a lot of people, writing isn’t just something you have to do as a job. It isn’t a chore that you need to do to raise your professional profile. It often isn’t primarily for others. It’s something they enjoy doing. And, sometimes, it’s something they must do. For those people, all the advice in the world is just material for them to consider rather then guidance.

And that’s why this is a somewhat unplanned, mostly unfocused, definitely meandering, non-peer-reviewed, and largely unstructured chunk of text. And if you thought the advice above was good and didn’t notice that I was largely not following it, keep that in mind.

If you’re not confident in your writing yet, or if you think you’ve hit a wall in your progress, try advice from others like the above. It may unstick you from where you are, give a bit of structure to your process for this next phase, even if you eventually outgrow it. (Also, if you’re writing in a work context - remember that writing is almost entirely about your audience and what you want to them to know, and very little about how you like to write.)

Conclusion

They tell me you should always have a conclusion section.