Writing Docs at Amazon

Scott
8 min readFeb 10, 2019

--

Recently, Ben Bashaw published a good article about the way that Amazon (almost uniquely) uses written documents to make decisions. This was posted to Hacker News and a lively discussion ensued. While I was at Amazon, I wrote or contributed to dozens of documents that were presented to Jeff Bezos. In the HN discussion, I was asked for some clarity on the do’s and don’ts of these documents, so I figured I’d write something up in longer form than a comment.

(Obligatory disclaimers: I’m speaking only for myself; I can only talk about what I saw; I no longer work at Amazon, so things may have changed; I wrote this note while recovering from a major surgery and still taking painkillers, so my thoughts may have been, umm, altered…)

In many ways, the rules of the road for an Amazon document are no different than those for good, clear writing in general. I was lucky enough to have a tenth-grade English composition teacher who thought that the 2-page essay was the most important form of writing of all; the “only thing you had to do” to get an A in her class was to write six, 2-page papers to her satisfaction (effectively, “perfect” by her rubric) during the semester, and you were set. But there were no grades for the individual papers; either a paper was “accepted” (basically, an A) or it was rejected, and returned to you the very next day, fully commented by her with everything that she found wrong with it. Then you rewrote it again and again until it was accepted. We hated her. But we learned to write.

So, in no particular order, here are some guidelines for writing an Amazon document.

(0) Amazon documents are generally paragraphs / prose. There may be some bullet points, but you’d be expected to back those up with real sentences in the document. Otherwise, it’s really just a PowerPoint in Word clothing. And, of course, there are likely going to be some tables of quantitative data.

(1) Use proper grammar and check your spelling. Seriously. People will think that if you ignore the little stuff, you are probably also careless with the big stuff. And many times, poor grammar can lead to ambiguity in meaning, which is what you are trying to avoid. If English is not your native language, that’s fine, work with friends or peers to clean things up (just as you would if you were building an Excel model). Understanding your own weaknesses, and working to compensate for them, is important.

(2) Understand what you are trying to accomplish with the document (as with anything you write). For example, is this a new project that you want to undertake (product you want to build)? Is this a significant change to a planned launch date or feature set (especially of a high-visibility project)? Is this just more of a status update? Is it an answer to a specific question or request that Jeff made, or is this something that you are bringing to him? One of the hardest types of docs to write was basically a “de-commit” document (Amazon is big on “disagree and commit,” so if you are coming back and wanting to de-commit to something previously agreed, you really had to have your data and logic clear as to what had changed since the plan was committed.)

(3) Minimize surface area / leave out extraneous stuff. The more “random” things you put in that aren’t directly related to what you are trying to accomplish (point 2), the bigger the chance of going off-topic and rat-holing, and the smaller the chance of accomplishing your goal. If something is in the document, the audience assumes that you think it’s important enough to discuss, so they will. If you have a bunch of important things to discuss with Jeff, it’s usually better to have separate meetings, even if they are consecutive. We once had four meetings with him in two days. It actually went fine ;)

(4) Have the right people in the room. The subject matter experts should be there. If you are discussing a design issue, yes, the VP or head of design will be there (and will have probably contributed to & helped edit what is being presented), but the individual graphic or UX designer who did the work should be there too, and should do most of the talking. If you are discussing a product feature that has some limitations due to deep technical challenges, don’t just have the PM and the general engineering lead there, but have the (in our case) natural language processing expert in the room; Jeff doesn’t want to hear the PM’s second-hand explanation of why we can’t just have Alexa do “x” — he wants to deeply understand it by talking to someone who’s probably got a PhD in that specific thing. [BAD MEETING]

(5) Check your ego at the door. The goal of the document is to get to the right answer, even if it’s not the one that you originally proposed. Jeff is a very smart person (he’s probably smarter than you are). He will almost certainly ask you questions that you didn’t think about. Be ready to debate, discuss, and change your mind. But also be aware that he is equally willing to change his own mind and he highly values that trait. He expects people to speak up and debate honestly and sincerely, based on data and logic; bringing in intuition is fine, as long as you’re willing to identify it as such and propose experiments on how to test it if challenged.

(6) Be sure to “show your work.” For example, if you had internal debates in the team about whether the recommendation should have been A, B, or C, write about all three and be explicit about why you think B is the best. Jeff has a broader picture of everything that Amazon’s doing than you do, and what seems obvious to you may be obviously wrong (or just unnecessary) due to some other initiative or some bigger corporate strategy. And seeing that you’ve done that work and looked at multiple options will lead him to trust you more.

(7) Represent and advocate for the customer. The customer’s the most important person in pretty much all decisions, and the only one not in the room. Write (seriously and convincingly) about why what you are proposing is good for the customer. One of the most frequent ways that candidates got negative ratings in interviews was to talk about Prime in the way a mobile operator might think about a subscription: selling the customer a subscription and hoping that they never use it. This Amazonian thinking (we want the customer to use Prime, a lot, and we need to figure out how to make that sustainable for the business) should suffuse your documents. This is part of why (almost) everything done at Amazon starts with a press release; the structure of a press release forces you to talk about the project in terms of why the customer cares.

(8) Don’t surprise or shock your peers (or your boss). This is pretty standard stuff at any company, but don’t go in the night before and make a bunch of substantive edits or changes to a doc that you, as a team, will be presenting, without letting anyone know. This will lead to a very. bad. outcome. (Generally, for you ;) )

(9) If the document is really not ready, think seriously about rescheduling the meeting, even with Jeff. In most cases, it is you (your team) requesting the meeting with Jeff, not the other way around. So, if you are not ready, and you go ahead, you are wasting the time of one of the busiest people in the world and he will get angry (and you will notice that anger…) [BAD MEETING]

(10) Think big enough. If your document is identifying a problem (“Hey, Jeff, we’ve now done enough in-depth analysis to see that there’s this big technical issue that will limit system performance and will hurt the customer experience”) and proposing a solution (“We’d like to double our hiring plans in this particular area, which would allow us to accelerate progress this much…”), think through the rest of the logic. For example, If there are competitors out there, where are they on the scale that you are describing? Will your proposal get you further ahead than they are? You don’t want Jeff to be the one to draw the conclusion, “So, what you’re saying is, we’re going to take 20 years to catch up to $competitor as things are, and your big plan is going to make it only take 10 years to catch up?!?” [BAD MEETING]

(11) Read the room. Sometimes you get into a debate / discussion with Jeff about some issue, and you know that your team’s position is right, but you just can’t convince Jeff. He’s a human being like anyone else; we all have those days. Speak up, say something like, “Jeff, we hear your points / understand your concerns; we think we’ve not done a good job explaining our thinking or gathering the right, conclusive data, and we’d like to come back in a couple weeks and discuss the topic again.” 9 times out of 10, he’ll be fine with that and, the extra time will give you time to dig in deeper. You may even discover that Jeff was right (that “smart” thing again), or you’ll come back, present the new data / new logic, and he’ll (very) happily say, “you guys were right, thanks for pushing on this.”

(12) Don’t be vague, and don’t be overly-dramatic. Present the numbers and let the audience make their own editorial evaluation. Don’t say, “many more customers who were exposed to the new UX completed the purchase process, while a far smaller number completed their purchases in the original UX.” Say, “567 of 982 (57.7%) of the customers who saw the new UX completed their purchase, while 481 of 1,108 (43.4%) who saw the original UX did so.”

In fifty meetings with Jeff during my time at Amazon, three of them went badly. I’ve marked the relevant situations above. At least we never made the same mistake twice ;)

I’ve written this from the point of view of writing docs for Jeff meetings, but the same basic guidelines apply at all levels, just with somewhat varying levels of depth and preparation. If you think of every doc you write as something that might end up being read by Jeff, you’d certainly be well prepared.

I hope that this is useful. Thanks for reading! (And please let me know if you find any grammatical or spelling errors.)

Scott (Blanksteen)

📝 Read this story later in Journal.

🗞 Wake up every Sunday morning to the week’s most noteworthy Tech stories, opinions, and news waiting in your inbox: Get the noteworthy newsletter >

--

--