Effective Writing

Clear and comprehensive communication skills are important for good engineers. Since a lot of day-to-day communication tends to be in written documents (be it in design docs, issue trackers, or Slack/Discord), I am always striving to be better at it. This is a collection of notes on strategies I've found useful to improve my writing:

1. Know Your Audience

This is a technique that a more senior engineer at Meta shared with my pretty much after the first document I wrote there. The idea is simple: define the kind of person that your writing is for in advance. And then write only for them.

I use this to get an understanding of what kind of previous knowledge I can assume from the audience and will make me avoid falling into the trap of using too much jargon or technical terms when writing for product teams and customers or being too broad and unspecific when writing for engineers.

The second thing I really like about this technique is that it will give you a cue when your writing is addressing an audience that is too broad. I realized this when I wrote project status reports that were read by my peers but also product managers, designers, and leadership. These reports should not be focused on technical details so instead I split up the report into two parts: one for my team and one for the rest of the organization.

2. Align on a Shared Goal

This is especially helpful whenever you reach out to someone for the first time. Before going deep into the details, give some context and align on a shared goal.

I use this all the time when I reach out to different engineering teams (within the organization or broader community), especially platform teams (so teams working on frameworks and infrastructure). People on these teams have a lot of requests from other teams so aligning to their goals is going to give you the best chance of getting your request prioritized.

What I do is usually a paragraph with the following content:

1. Some context as to what I am trying to do (what is the feature you are building and why is it important)
2. Connect to their goals (e.g. we want this feature to be reliable, fast, or efficient.)

3. Follow a Cohesive Train of Thought

Whenever I work on a longer document, I try to come up with one cohesive thread ahead of time that I try to follow with a relatively fixed pacing.

This is a bit hard for me to put in writing since I rely on intuition for this. One example is when I write a proposal for a new feature, I start with setting up the context and goals first, then explain the problem in more detail, then discuss the different solutions considered and narrow down on the proposed one before I conclude with the next steps necessary to move along. I try to give all sections the same amount of detail so that the reader can better orient themselves in the text.

I don't think the actual structure matters too much as long as it's consistent within the piece.

4. Avoid Hierarchical Components

Do you know the feeling when you read a book and it lingers in your mind for months afterwards? This happened to me this year with The Courage to Be Disliked by Fumitake Koga and Ichiro Kishimi. This book introduced me to Adlerian psychology and the concept of vertical relationships—relationships with a hierarchical component like boss/employee or teacher/student.

It's hard in a work environment to not have vertical relationships, however I do think that relying on this hierarchy will help you write more effectively. Instead, I try to meet eye-to-eye with the reader and try to write from the same level. Creating a shared goal helps a lot with this.

5. Do One Level Of Homework

Whenever I write something, I take a few minutes afterwards to think about the immediate next question that a reader might have and then incorporate the answer into the writing. This works great for any documents but is especially helpful when I need to ask for help as it will sometimes even answer the question that I had in the beginning.

I started to call this "doing homework" and my intention is to save time for the reader and thus improve clarity. I need to work hard to only do this for one level, though, since it can be easy to get distracted this way.

6. Keep It Short and Simple

I used to be really impressed by Software Engineers that write long prose with lots of fancy vocabulary even if I never fully understood what they were trying to communicate. If I don't understand what they are trying to say and it "sound smart", I concluded that I must be stupid.

This, of course, is nonsense and making your readers feel small is not something to aspire to. Instead, I try to keep my writings as inclusive as possible by focusing on simple and concise wording, even if this means that I have to put in more work.

Conclusion

Effective written communication is hard and the only real way I found to improve them is by practice. The points above might seem trivial to some but they have not always been trivial for me. Who knows, maybe you can try one of these ideas the next time you write something? If so, I'd love to hear about your experience!