https://pnewman.org/writing.html

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
          o "People are saying..." (Which people? How do they know?)
          o "It has been claimed that..." (By whom, where, when?)
          o "Critics claim..." (Which critics?)
          o "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.