Writing Well #

A common mistake I have seen engineers make in their projects is to start with an engineering design doc, extend it to include milestones and plans, and then augment it with API documentation as things are shipped. Over time, as more questions come in or as incidents happen, engineers add some What to do when … in the same doc, and may even add a FAQ section. This causes documentation bloat and is very ineffective. The resulting document is excruciating for readers.

I have seen this happen over and over again. Unless some other authority sets guidelines, the above-mentioned approach is the most straightforward and does not require much planning. This is often why the same engineers are unable to expand their scope and take on new projects — poor writing keeps them stuck maintaining the projects they built in their first two years. Unfortunately, the only feedback they get is “X has insufficient documentation”, which leads them to write more, which causes the original doc to be longer, which exacerbates our original issue.

Quick Framework #

I recommend using this framework for each new piece of writing.

1. Identify your audience. #

• Who are they?
• What context or environment are they in when they open this document?
• What are they looking for?

2. Choose your format(s). #

• What are all the different ways to convey the information to my audience?

3. Imagine how different segments of your audience will use your material. #

• How will a newcomer use this?
• What are some examples of successful communication that I can emulate?
• How will they find this document?

Example: Adding a Tutorial for Searching Logs By Request ID #

• Who is our audience?
  • Someone new e.g. just joined and is onboarding.
  • Someone who is refreshing their skills e.g. just before on-call, or after a long hiatus.
  • Someone who is trying to investigate a customer issue, and trying to self-help before asking in #ask-observability.
• What are they looking for?
  • They probably have some request ID in hand, supposedly from a support ticket or a request log.
  • They are hoping for a short guide on how to use this request ID to find their next clue.
• What’s our format?
  • Written instruction describing the steps, best practices, and the different options.
  • Loom demonstration.
  • Screenshots and examples.
  • Saved searches or dashboards in Splunk.
• How do we imagine someone using this?
  • Refresher: get a query that they can copy-paste, maybe even a Saved View that they can reuse.
  • Investigation: concise summary at the top, before they decide if they want to read further. This is but one of many possible paths they are considering.
  • Newcomer: detailed demo, that they can follow along step-by-step to build confidence.
• What are some examples of successful communication that I can emulate?
  • Screencasts on Railscasts.com.
  • Other examples of Detective Training from our wiki.
• How will they find this document?
  • Included as part of onboarding boot camp.
  • Linked from PagerDuty alarms.
  • Linked from On-Call cheatsheet.

Choose Your Format(s) #

If your projects are successful, you will have to write very many documents in different formats. Having to come back to this table over and over again is one sign of success. I congratulate you.

Sometimes, we might find ourselves needing multiple formats with duplicative content. For example, we might need

• an executive overview, containing just the high-level summary and the business impact
• a technical reference doc, containing the details of how the system is built
• a quickstart, containing a tutorial that adopters can use to get onboarded
• a customer-facing announcement, containing a summary of the upcoming change and planned timelines

Reference Documents #

Long and detailed, preferably organized to encourage drill-down and further discovery.

• How do I assemble this?
• What does this do, and how does it do that?

Tutorials #

Long and detailed, preferably in some chronological order or educational sequence that introduces a series of concepts.

• There are too many new words. How can I get started?

Cheat Sheets #

Very short; preferably with diagrams, tables, or some other visual aid. Should link to the more detailed reference docs.

• Which one of the 6 types of quantum flux capacitors do I want for my current problem?

Runbooks #

Short sequence of steps. Preferably a checklist that can be used in an emergency.

• The door plug on my plane has blown out. What do I do?

Guidelines & Standards #

Very well organized by some hierarchy, with one short section for each component.

• What can I expect of other users?
• What should other users expect of me?
• (e.g.) How frequently do we update Django here?

Roadmaps & Plans #

Length varies, depending on complexity and size.

• What are our plans for the next quarter, and the next year?

Discussion & Design Docs #

Length varies, depending on complexity and size.

• How are we solving X?
• Why did we solve Y this way?

Announcements, Release Notes, and Changelogs #

Short, with links to more detailed reference documents.

• Wait why did the UI/API change?! Ugh, you guys broke everything. Again.