by Patrick Newman ( and Azeem Jiva. Originally written in 2022, revised 2023-October.

A major part of my job at large technology companies has been reading, writing, and editing documents explaining various issues and what can be done to address them. I think it's a more important skill than people generally realize, as it may be the one way to reach someone in a different time zone, or who couldn't make a meeting, or who you will never speak with in person. Effectively written documents also have a way of hanging around, so investing in them can pay back over the long term.

I've also learned through experience that there is value in good writing in ways that aren't always obvious. A well-articulated error message in a log file or api response can save an engineer significant time, for example.

Over the years I've gathered a set of guidelines that have worked for me. I've made it a habit of sharing this type of stuff internally at the companies I work at, but none of this is specific to any company, so I'd like to share publicly this time.

This list benefited from feedback and revisions provided by professional colleagues of mine. I won't name them here, but thank you to those of you who read drafts of this and offered feedback.

Know Your Audience

Know who you want to reach, what you need them to know, what context they have/don't have, and what you want them to do with the information you will convey. Make it as easy as possible for them to get what you need from your communication. Be clear if there is a call to action or follow up you need from them, and by when.




This set of suggestions is primarily relevant to longer form documents, proposals, and emails.