On Writing Documents

It has been broadly observed that Amazon is powered by a writing culture. Meetings at Amazon typically begin with at least twenty minutes of silent, communal reading. PowerPoints are rare, reserved for presentations to large audiences. However, I haven’t seen a lot of discussion of how Amazonians approach writing documents.

This document attempts to address that gap. It describes my approach to writing documents at Amazon,  a distillation of a couple decades experience writing and presenting documents to Amazon leadership. I won’t claim this is “the Amazon Way” to write documents… but it is my Amazon Way. Hope it helps somebody out there.

Summary

Clear writing is easy to understand. It is frugal with a reader’s time and attention, presenting ideas simply and in a coherent order. This document describes an approach to writing intended to make it as easy as possible for a reader to understand and evaluate the ideas being presented.

Your document will succeed if it convinces the reader of three things: first, that your idea matters; second, that you understand how to address it; and third, that your proposal in fact does so. In short, your document should describe why, what, and how.

The “who” also matters. Remember that we write in many forms, from a new business proposal for leadership to a promotion assessment to documenting systems for engineers. Every document must be tailored to the specific audience for which it is intended. Every reader has a different mental model or different focus, typically associated with their role, expertise, and exposure to the topic; avoid repeating what they already know or providing details they don’t need. (See Appendix 1 for more discussion of the “who.”) This document is written for relatively experienced writers who are interested in tips and techniques to improve their craft.

We may sometimes fall into the trap of launching into long, ornate sentences that convey ideas in elegant and extravagent textual tapestries, hoping to establish credibility or persuasive power through eloquence and impressive vocabulary. This typically undermines our narrative. Simple language is easier to process and keeps focus on the ideas. Strive to be both succinct and unambiguous; it can be hard, but the best documents achieve both at the same time.

Most people can keep only about seven ideas in their head at a time (see Appendix 3). Our writing should be so clear and focused that the reader never needs to consider more than seven things at a time.

The best way to reduce cognitive load on your readers is to make sure they are never guessing where you are going:

1. State your ideas up front. Open with an executive summary.
2. Always start with the most important idea and end with the least important ones.
3. Elaborate only if needed, and then minimally.
4. Postpone complications or elaborations to the end, preferably to an appendix.^[1]

Start strong! This applies to the document; it applies to each section; it applies to every list; it applies to each paragraph. It even applies to each individual sentence: “idea because reasons” is more powerful than “because reasons, idea.”

WHY: Describe the Problem

“The most important thing is to keep the most important thing, the most important thing.” – Franklin Covey

Readers must understand the problem before they can evaluate a solution. At Amazon, every problem is a customer problem. We always start with the customer and work backwards, so your document should start by connecting to the customer need you are addressing. Then frame the problem in a way that the reader understands the value of solving it, no matter what you are trying to describe. Describe the impact on the business, in business terms. This is equally true whether you are describing a new program, a new product, or a new technology; every technical design document ultimately describes a way to impact a customer need, albeit perhaps indirectly. If the customer impact matters, we should be able to measure it.^[2] This means this section should always include goals.^[3] After you succeed, how much better off will your customers be? Don’t start with the “what;” make sure you’ve clearly described the “so what.”^[4] Be frugal here as with the rest of your document: include only data that matters, that drives to the heart of the problem.

You should also frame the timeliness of the problem: “why now?” What are the risks in not solving it? What are the risks of solving it later?

By the time the reader has finished the first section, they will understand why the problem matters. If you’ve done this well, your reader may be alarmed. Being asked “why aren’t you already working on this?” or “do we have enough funding for this?” is a sign you’ve succeeded.

WHAT: Describe the requirements.

“For every complex problem there is an answer that is clear, simple, and wrong.” – attributed to H.L. Mencken

The reader next needs to understand what makes a solution a good one. Articulate the success criteria. Make it clear that you know what your customers want, and how to decide if you’ve addressed it. This section must establish a clear mental model of how you are thinking about solving the problem. Tenets are an effective Amazon mechanism to help establish this. (I plan to write a follow-up on crafting good tenets soon.)

You will have established the business goals in the first section; here in the second section you describe the requirements for a solution, including if possible health metrics that assure you are on the right track. Business goals are your outputs; health metrics establish the inputs. You should make it clear that you know what is necessary and what is sufficient. If you have data, use it. If you have testimonials, include them. Even better, run experiments and describe the results. (I plan to write a follow-up on crafting good metrics soon.)

This is your opportunity to describe the customer persona(e) to which your solution will apply, if what you are proposing has a specialized audience. Do not give in to the temptation to be vague: be specific and crisp. Don’t describe a life story (“22 year old college graduate”); describe a person who needs what you will provide (“a young person seeking a job”). If you can’t satisfy every customer, establish who you are focused on, who you have left out, and why. A user story is often a good way to achieve this.

This is also a good opportunity to articulate how you will know when to stop and reevaluate your solution. What are the failure criteria? How are you front-loading the risk? Failure is good, if you do it right.

You should describe constraints that force trade-offs. Are there unique time-to-market constraints? How much engineering quality is acceptable to sacrifice to meet them? If there are existing customer expectations that need to be reset, or existing solutions with which you need to interoperate, describe them. For technical documents, what are your key performance metrics and SLAs (Service Level Agreements)? Also consider ways to relax constraints to make the problem easier: “the customer needs an answer within minutes, not seconds” creates the opportunity to change a policy rather than build complex technology. Be wary of artificial constraints. These often arise from implicit, shared assumptions; the writer’s job is to make them explicit to ensure they’re real.

When the reader has finished the second section, they will understand the characteristics of a good solution. They are now ready to evaluate how you propose to solve it.

HOW: Describe your solution.

“When I’m working on a problem, I never think about beauty. I think only how to solve the problem. But when I have finished, if the solution is not beautiful, I know it is wrong.” – R. Buckminster Fuller

Now, at last, tell the reader how you will build a solution; tell them what you are going to do. If you have written the first two sections well, it should be more straightforward to describe your solution, and easy to evaluate how well it addresses the customer need.

Note that this is not the place to describe options you’ve considered. You’ve thought about the problem hard, you’ve made difficult trade-offs, and you’re ready to describe your conclusions. If you aren’t ready to do that, you aren’t ready to write your document. Where the trade-offs may be important, add a footnote – or better, push the considerations to an appendix and treat them thoroughly: why was it hard? What are the tradeoffs? How are you going to solve it? (See what I did there? “Why, what, how.”)

Be clear on what you want from the audience, and make sure this section sets up the right conversation. We often write documents as a way to consult with other leaders, soliciting guidance or a decision. For such documents this section should clearly articulate the key decisions you need reviewed. For clarity, you should also consider adding specific questions to the executive summary. Many documents are intended instead to present information: progress report, situation report, or summary of remediation for a failure. For these documents, the audience is typically familiar with the why and how; this section should present unambiguous reporting.

Written well, any document can have transformative impact. I hope that these ideas can help you improve your writing.

Remember, however, that that strict adherence to all the guidance may result in formulaic, lifeless prose. These should be viewed as best practices, or perhaps as ideals towards which to strive, not as straitjackets that strangle eloquence or progress.

Appendices

Note: These appendices serve to help assure that this document serves both as a description and an example of how to write a well-organized document.

Appendix 1: Know Your Purpose

“Your audience is one single reader. I have found that sometimes it helps to pick out one person – a real person you know, or an imagined person – and write to that one.” ― John Steinbeck

It is often difficult to decide what to include in a document. Remember that the battle is more often lost by giving needless information than won through eloquence. Be decisive: be as brief and direct in your main narrative as possible. However, do not postpone or avoid controversy. Being up front with difficult topics builds credibility. Use an appendix (or a supporting document you can provide on request) to go into depth about fine-grained trade-offs you’ve made or alternatives you’ve considered.

To decide what is  part of the core idea and what is supporting material, you must be sure to understand the intended audience before you start. Your document should be tailored to that audience. Amazon’s global and business diversity makes this a challenge, but it is essential to writing a powerful document. Consider describing what you want from the reader in the executive summary, if you want something specific. If your readers are already familiar with the space, you can limit the “why” and “what” sections to a brief summary, with a reference to the document that provides a more thorough treatment.

But consider the statement “you need to know your audience” itself. That is inadequate guidance. How does the language change for a technical vs. business vs. operations document? How does the focus change for a general audience, for executives, for senior executives, for a CEO? This topic is too deep to include here, and so the details are out of scope for this document.^[5]

Related, but less important, “The rule of three is a writing principle that suggests that a trio of events or characters is more humorous, satisfying, or effective than other numbers.”^[6] The phrase “why/what/how” is simply more impactful than who/why/what/how. Further, articulated fully the phrase would be who: summary/why/what/how, and that’s quite unsatisfying. So I have chosen to focus this document unambiguously on the simpler and sufficient trio of why/what/how.

Appendix 2: Cognitive Load

In writing this document, I debated how much detail to provide about cognitive load; it is a topic I find fascinating. The basic idea of the “rule of seven” stems from a seminal study performed in 1956 by George Miller, and for this reason is sometimes referred to as “Miller’s law.”^[7] Of course, that is outdated and oversimplified, and there have been significant advances since. Recent studies suggest that seven is the average; talented people can track up to 14 concepts. Since senior executives are typically talented, it might be tempting to ignore the rule for a such an audience. However, remember that they also bring a lot of external context to their reading, which occupies a lot of their attention. In fact, they’re often thinking about ten other related concerns, and so they may in practice have less cognitive bandwidth available for your document than the typical reader. It is always better to stick to seven or fewer.

The rule of seven describes “cognitive capacity,” which is occupied by “cognitive load.” Load is separated into three types: intrinsic, germane, and extraneous.^[8] Intrinsic load represents the unavoidable work necessary to understand a topic. Germane load is the work required to construct a mental model to make sense of the topic. Extraneous load is the work imposed by how the information is presented. This document is primarily aimed at reducing germane and extraneous load, presenting techniques that help organize information into units (formally “schemas” or “chunks” – see below) that are more easily digested by a typical reader.

Using some internal Amazon terms, a reader’s ability to understand the topic depends on how closely their existing mental model aligns with what we’re describing. The germane load of constructing the model is made considerably more difficult if our ideas conflict with the existing models in a space. The germane load to change existing mental models often significantly outweighs the intrinsic load. Hence there is a strong temptation to try to anticipate and catalog existing, competing mental models and then bridge the gaps. However, doing so in the main narrative typically distracts from the intrinsic description and impairs your document. If there is a significant mental model you’re trying to change, it may be worth discussing it explicitly and comparing it to the new model, but if you do that make sure to keep it out of your main narrative, typically in an appendix. In short, use your document to attack the intrinsic load. For a successful document, the conversation in the room will focus on the germane load.

A related term in cognitive theory is “chunking,” which describes how the brain organizes related concepts into related groups processing; for example, as an operator learns Morse code, their brain moves from processing individual sounds to recognizing characters, then words, and eventually phrases. Introducing big patterns and discussing the relationship between them creates chunks; as we move to more fine-grained detail, introducing sub-chunks within those anchoring topics, we reduce the overall cognitive load. This entire document is an effort to introduce a useful overarching chunking for writing documents. Following a common form will reduce load on all readers familiar with it.

All of which means that the purpose of this document is to describe techniques that reduce distractions and make your ideas as easy to understand as possible.

Appendix 3: The “Why” Trap

There are some warning signs that can help indicate a lack of clarity. The purpose is to avoid describing how you feel: don’t explain why or how much you believe something is impactful. Focus on the facts. Connect the data to the narrative. Defend the narrative with data.^[9]

Be Objective and Specific

The three sections described here are really just different forms of “what:” the first is “what is the impact,” the second is “what are the requirements,” and the third is “what should we do.” But often in writing we move away from the “what,” the objective data that informs our decisions, and instead describe our personal “why” in the form of our subjective state: the perceptions, interpretations, or motivations that led us to a conclusion. Strong writing uses data to describe potential impact, rather than describing how we feel or a priori reasoning. Representations of internal state or judgment impair writing, as they are typically not useful to people who don’t know us well. The best indicator that we have fallen into this trap is substituting emotional language for data, using adjectives or relative sizing (often described as “weasel words”) rather than numbers. Consider the difference between “massive data set” and “14.3 petabytes;” between “real-time” and “latency less than 8ms;” between “huge customer impact” and “decrease T30 EDR (Trailing 30-day Expressed Dissatisfaction Rate) from 13.1% on 12/31/2019 to 11.3% on 12/31/2020, an improvement of 2500bps (18%).”

Use (the right) Data

Make sure you include all the necessary data, but also make sure that every piece of data you present is necessary. Each metric you present should be directly relevant to your goal. If you’re writing a promotion document for an engineer, technical information (dataset size, latency, availability) is more important than business data; include both, but focus on the former. Including irrelevant data increases the cognitive load for your audience, distracting them from your point as they try to figure out why the data is included or what it tells them. It is the writer’s job to provide metrics that effectively drive the narrative, rather than leaving the reader to choose from a list.

Appendix 4: Visualizations

You can strengthen your document with visual information in addition to the simple, powerful words of your narrative. Graphs, diagrams, tables of data, screenshots or mocks, and quotations are all tools that can convey rich information in a condensed form. Used well, they can transform your document. Used poorly, they can create confusion and derail the narrative completely. Use them sparingly. When you use one, put in the work to assure it is impactful. A picture occupies space on the page, and it must communicate more than the words it has displaced. If a picture is worth a thousand words, a bad picture is a lot of gibberish. Don’t forget to verify it looks good in black and white; those red, blue, and grey lines often end up invisible or indistinguishable when printed.

(A word of terminology: I consider anything fundamentally aimed at presenting data to be a “graph,” while something aimed at describing interactions between systems or ideas a “diagram.”)

Graphs

Graphs are particularly powerful, and used too rarely. A strong visual display of quantitative information can transform a conversation. A good graph is not generated using the defaults in Excel, however; creating a good graph takes care and work. To improve your use of graphs, consider reading “The Visual Display of Quantitative Information” ^[10] and “Visual Explanations,”^[11] by Edward R. Tufte. Use the right kind of graph: the world hates pie charts, but there are many choices other than a simple line graph or histogram. Box plots, heat maps, small multiples, and many others can serve to effectively convey a lot of information quickly.

Make sure your graphs are:

1. Dense. More dimensionality to the data is better. Tufte’s favorite graph is Minard’s graphic of Napoleon’s march to Moscow. It includes many dimensions displayed simultaneously: latitude, longitude, time, casualties, temperature, and more.
2. Clear. It is important that the data be consumable without undue explanation. The Napoleon graph is elegant, even sublime, but requires explanation and real thought to understand. Be sure the cognitive load is worth it.
3. Honest. Visual presentations must tell the truth.
   1. Numbers should be proportional to quantities represented.
   2. Every axis must have labels that do not distort or add ambiguity. Typically every axis should start at zero.
   3. Draw focus to data variation, not design variation.
4. Frugal. Maintain a high data to ink ratio. Above all else maximize the amount of ink that represents information and minimize flourish.
   1. Make sure the data is strong and foreground, the axes and labels are subdued (but legible!) background.
   2. Remove any and all chart junk: 3d effects, drop shadows, etc.

Diagrams

Many documents, in particular technical design documents, include diagrams. Most diagrams can be significantly improved.

1. Remember the rule of seven: your diagram should only have seven boxes in it. If you need more, start by creating useful chunks (see above): introduce the major areas of focus with no more than seven boxes, and then use another diagram (or seven!) to fill in those concerns with specifics. That gets you to around 50 related ideas. If you need more than that, you’re doing something wrong.^[12]
2. Avoid visual clutter. Align all horizontal and vertical edges. Make your lines orthogonal, and avoid line crossings if possible. Beware multiple closely adjacent parallel lines; they blend together and are difficult to track individually. Use line labels sparingly. …and break these rules deliberately to call attention to anomalies.
3. Don’t try to make a diagram do too much work. To describe the relationship between systems, use a data flow diagram. To describe how systems interact, use an interaction diagram. Do not mix the two.
4. If your system stores data in more than one table, include a schema diagram. This is especially true if you’re using Dynamo DB. Although the technology does not support schema, the data relationships are still key to understanding your design.

Appendix 5: Additional Suggestions

Don’t be formulaic

Everywhere in the world, we are introduced to the persuasive essay in our teens. Everywhere in the world, we are taught wrong. We are taught that writing follows a disciplined format: in an introduction, we state that we are going to discuss topics A, B, and C; then we discuss A, move on to discuss B, and then add a third section discussing C. We then conclude by repeating that we have just discussed A, B, and C – and add a dramatic, inspiring hook to dazzle the reader. Indeed, this is so ingrained that I received many suggestions that this document should use that approach… even after I wrote these paragraphs repeating emphatically that for professional writing, this approach is utterly wrong. Please don’t recommend it to me.

Because while this approach can be effective in pedagogy, it results in writing that is tedious and repetitive. Teachers want to “see our thinking” so they can give a grade; in a professional setting people just want to understand the problem and evaluate the solution. We should approach writing with the assumption that our reader is busy and may be interrupted at any point and never return to the document. We must maximize the value she gets from every sentence she encounters. So we start with the conclusion: open with an executive summary that relieves a reader who already understands the topic from the need to read the document at all. We then proceed from the most important ideas to the least important, explaining only what is needed to assure understanding. Thus, after an executive summary, we always proceed through three sections: why, how, and what.

Just Write

Getting started is often difficult; a blank page can be a formidable opponent. Many experienced writers suggest it’s easiest to work iteratively. Start with an outline: translate “why, how, what” into headers relevant to your topic, then jot down the highlights you’d like your audience to take away in each section. For those highlights, identify the key metrics. Write the “move .. from … to” sentence, using placeholder X’s and Y’s or TKs (“to know”, basically “coming soon”). Then start gluing the concepts together, moving iteratively toward a well-structured document. Of course, other writers have their own process; some start by simply writing everything they can think of without considering structure, and then reorganize later. The most important thing is to start. (One subtle tip: for a draft document, use the version number to express how complete you think it is, so “Draft 0.8” suggests the author believes the document to be 80% complete).

Write Goals Carefully

When you describe goals, make sure they follow the full Amazon format: “Move [metric] from X [units] on TK [date] to Y [units] on TK [date], an improvement/decline of Z [units] (Z’%).” Include both Z magnitude and Z’ relative change; yes, Z=Y-X, and Z’%=Z/Y, so a reader could do the math. But this approach reduces cognitive load by not forcing the reader to do that extra work. If X and Y are percentages, express the magnitude in bps (basis points, 100 bps to a percentage point), but include the relative change Z’ as a percentage (see the final example above in Section 3, “The ‘Why’ Trap”). Always, always, always use this format!

Avoid Jargon

Make sure to use broadly understood language; stay away from jargon. Where appropriate, refer to touchstone definitions, such as the Amazon Leadership Principles or Principal Engineer Tenets. If you must use domain specific vocabulary, make sure to clearly define the terms. Acronyms are domain specific, so expand every acronym the first time you use it, even e.g. AWS (Amazon Web Services). If there is a lot of jargon, include a glossary. If the relationships between the ideas is complex, consider using a schema diagram instead or in addition.

George Orwell was an Excellent Writer

From George Orwell’s Politics and the English Language:

1. Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
2. Never use a long word where a short one will do.
3. If it is possible to cut a word out, always cut it out.
4. Never use the passive where you can use the active.
5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
6. Break any of these rules sooner than say anything outright barbarous.

It Takes a Village

Remember, document writing is a team sport. Get as many people to read, review, and provide feedback to your document as possible. Note that the “why/how/what” structure lends itself to iterative feedback: you can circulate and iterate on the “why” before writing the “how,” and on the “how” before the “what.” You can even work on getting feedback before starting the document: vetting your ideas verbally or on a whiteboard is an efficient way to refine ideas before investing in articulating them clearly. If it is appropriate to give credit, give credit fully: distinguish authors and contributors, acknowledge reviewers if needed.

Stop Digging

Fight the temptation to immediately add more explanation when people are not convinced. Make sure you understand the cause of the confusion; it is often due to a misunderstanding of the preceding sections. Make sure your readers understand the connection between what you’re proposing to do and how you’ve described the requirements, and the connection between those requirements and why it matters to the customer. Elaborating a description of a technology won’t help address confusion about the requirements. If they do understand but simply aren’t convinced, typically this means you don’t have enough or the right data.

Frequently Asked Questions

If your document has significant complexity, it is good practice to include a FAQ (Frequently Asked Questions), and the first question is often “What are your hotly debated topics?” However, include this question only if you have had (or are having) real debates; a tepid discussion with a clear winner wastes your reader’s time and serves to undermine the credibility of the document. I personally approach the FAQ as actually that: I include only questions that have really been asked. Others believe the FAQ can be used as an addendum, to answer questions that the narrative cannot. Use your judgment. Do remember that most documents will be re-read by new team members someday, so it is good practice to document the questions that were asked in a document review in the final version of the document, to help those future leaders “respect what came before.”

Additional Resources

How to Write Usefully, by Paul Graham. A well-constructed discussion of what this paper doesn’t address, how to reduce extraneous cognitive load.

How Great Leaders Inspire Action, a Ted Talk by Simon Sinek that is closely related to this paper.

Footnotes

1. Or a brief footnote, typically no more than two lines. Deferring explanation helps avoid wasting your reader’s time and attention describing things they already understand. If they have questions, they can go dig in. If not, they can simply agree and continue. ↑
2. Measurement is a quantitative reduction in uncertainty. See “How to Measure Anything,” by Douglas W. Hubbard. https://smile.amazon.com/How-Measure-Anything-Intangibles-Business/dp/1118539273 ↑
3. In some cases we may only be able to measure the value sometime far in the future. Still, if it is indeed an impactful area deserving investment, there should be strong, concrete evidence that there is opportunity, or at least that something is awry. Your document should provide evidence to  establish that there is a problem to address. ↑
4. If you are describing goals, make sure they follow the traditional Amazon format: “Move [metric] from X [units] on TK [date] to Y [units] on TK [date], an improvement/decline of Z [units] (Z’%). Yes, Z=Y-X, and Z’%=Z/Y, so a reader could do the math. But this approach reduces cognitive load, giving both absolute and relative change without forcing the reader to do extra work. Always, always, always use this format! ↑
5. Also, I’m not the right person to write it. ↑
6. https://en.wikipedia.org/wiki/Rule_of_three_(writing) ↑
7. https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two ↑
8. https://en.wikipedia.org/wiki/Cognitive_load ↑
9. Many Amazon writers finish editing their document by searching for and excising words ending in “ly.” Adjectives are no substitute for data. ↑
10. https://smile.amazon.com/Visual-Display-Quantitative-Information/dp/0961392142 ↑
11. https://smile.amazon.com/Visual-Explanations-Quantities-Evidence-Narrative/dp/0961392126 ↑
12. The work of simplifying and cleaning your diagrams can clarify and de-complexify your solution. If it’s hard to represent each chunk of your idea in seven concepts/boxes, it is even more valuable to invest in figuring out how to do so. ↑