by Patrick Newman (patorick002@gmail.com) 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.

Headings

• Titles: Make your doc title meaningful and discoverable in search.
• Email Subjects: Make the subject scannable so the reader knows whether they need to read and if there's an action that they need to take.
• Subheadings: use them to make your long document or email more easily scannable.
• The subheading of a paragraph should summarize what the paragraph is about.
• Write the names of the authors, contributors, and reviewers at the top of the document. Most templates have this. Do it for everything.
• Include the date the document was started. I prefer the format YYYY-MM-DD because it is the international standard, and avoids ambiguity between the American and British formats. Spell out the month for extra clarity.

Introductions

• If there is a specific proposal in the document, put it right at the top. This gives the audience the option to decide whether to read the whole document or not.
• Example: "This document proposes developing a Twitter client for the Atari 2600 platform, funded with four software engineering headcount and a target release date of June 1983."
• Set a clear expectation for the audience up front. Sometimes I write a "How to read this document" section to clarify what to expect.
• Example: "this is a collection of notes on an early stage product, no major decisions are being proposed yet."
• As a rule of thumb, I normally write my introductions last, after I have written the rest of the document. This is because I don't necessarily know what I will write in advance.

Content

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

• Avoid making assumptions about what your audience knows. If assumptions are unavoidable, make it clear what the assumed knowledge is.
• Define key terms that may be unfamiliar to the audience. Example: "Atari 2600 is a video game console that was popular in America during the early 1980s."
• Be as specific as possible. Words such as many, almost, nearly, significantly, better, worse, etc imply different things to different people. Being specific takes away this ambiguity. 93% of bugs, increase of 7% performance, etc. The specifics also show that you are speaking from a place of knowledge instead of filling in content.
• Follow the Amazon rules, particularly:
  • Replace adjectives with data
  • Avoid "weasel words" - words that are ambiguous or misleading. Examples, taken from Wikipedia, including
  • "People are saying..." (Which people? How do they know?)
  • "It has been claimed that..." (By whom, where, when?)
  • "Critics claim..." (Which critics?)
  • "Questions have been raised..." (Implies a fatal flaw has been discovered)
• Avoid inside jokes and pop cultural references in the core points of the document. These might increase engagement for some, but exclude others who aren't in on the joke.
• Read up on inclusive language and make sure you aren't including outdated terms.
• Put reference links in an appendix section.
• Define acronyms, abbreviations and other key terms that reader may be unfamiliar with at the beginning of your document
• Add visuals if possible - charts, graphs, architectural diagrams, etc.
• Avoid condescending words (obviously, of course, clearly)

Editing

• Edit your documents for clarity and correctness. Take a break between writing and editing.
• Have a few trusted early draft reviewers, who can give you feedback before you share widely.
• I try to focus on removing unnecessary detail and content when I edit my writing, to amplify the most important points.
• Remove redundancy. Are you saying the same thing 3 different ways?

Reading

• Make time to read others' documents.
• Share interesting things you read with others.
• Don't be afraid to give positive feedback.