"Writing is nature's way of letting you know how sloppy your thinking is." -Dick Guindon, via Leslie Lamport
Every so often, I have a coding question and I have an urge to ask that question on StackExchange.
Before I actually post the question, I write a draft question. I usually revise my draft a few times to make it as clear as possible. About 50% of the time, the process of revising my draft makes me realize an obvious solution to my own problem that I had overlooked.
A former colleague of mine had a teddy bear on his desk, before you could ask for his advice you had to take the teddy and explain your problem out loud to it. Easily 80% of the time you'd return the teddy and go back to your desk with the solution.
I found when I quit smoking my ability to solve complex problems took a dip, because I wasn't taking the cognitive break to step back and reflect on problems. Once I replaced my smoke break with a walk around the building my work went back to it's usual level.
Turns out you also have to use them for it to have any benefit, and most people don't.
Over time, as a more general populace joined the Internet, the ethos changed to act more as a support system rather than the more demanding expectations of the past. Presumably that was due to a recognition that newbs did not have the exposure to computing or tech that the prior generations of users had and so the intent was to be more educative so that these new users could learn to solve things for themselves. Alas, that optimism was misplaced as the majority of people are not interested in thinking for themselves but instead just looking to follow a checklist with no understanding.
FWIW, some four years ago I wrote this for this "bug filing recommendations" guide for the OpenStack community when triaging lots of bugs.
In my experience, the most and informative and delightful bug reports I've ever come across are from Japanese customers. And obviously, I prioritize those bugs that are competently written.
It won't let me login.
It won't let me change my profile.
It won't let me go to the page I want.
Such a waste of time. Two seconds of thought should allow anyone to realize that is not enough data for me to even begin troubleshooting your problem.
I was using Welcome.js instead of Home.js
I was happy, kinda. But also, wondering if I solved the issue earlier in the week.
The best part is running into the same problem years later and finding your old answer when searching.
If not, it’s almost like an incognito version of the dreaded “never mind, I found a fix”-follow up post.
Nearly relevant XKCD: https://xkcd.com/979/
In my daily routine, the thought of printing anything for work seems peculiar.
I feel the same, but at some point I started to do everything work-related digitally because people would often comment on this. The craziest one was someone pointing out this would lead to ideas that are too complicated.
Making the presenter bring everything needed to have a distraction free conversation is a feature, not a bug.
Any other rules of thumb for people who are trying to adopt this ?
Digitally has 2 big benefits:
- You can see when someone is commenting on a thing and skip down so not everyone dog piles on the same thing.
- In lower level meetings you are very unlikely to have a note taker, so in digital form everyones notes are in one spot. In the paper form of the meeting you either collect / decipher everyone's notes, or you have argue/defend/explain your doc while also taking notes.
Paper is better for:
- Keeping everyone focused. You don't pop that laptop until you're done marking up the doc, people often don't even bring laptops to paper doc meetings.
- keeping comment arguments from forming in the margin in the digital document.
Some parts of amazon are trying to do it digitally, esp those that are remote.
The reason you do it in the meeting is that for more senior people, you have to block them off time to think about the document. Asking people to schedule another block of time to give feedback on YOUR problem is rude. As you get more senior you end up in way more meetings. It's hard for more junior people or ICs to understand in a lot of cases. If timing is hard, have them schedule you in a different slot.
You can tell in say google docs where everyone is reading wise. You can also see all the comments so you can also judge progress.
Ask questions in negative every 5-10 minutes "Does anyone need more time".
Once everyone is ready, start the meeting by going through comments from top to bottom.
After that it runs like a normal N-Pager meeting, or tech review or whatever.
I will say that with say google docs you can use suggestions and other things or say "I'll work on that". And just move on. It's rarely important to rabbit hole on the english, esp on engineering docs. If you're writing a actual PR or marketing doc, sure.
The features I find useful are:
- Cursor Position of readers (minor)
- Suggestions (like google docs), helps with minor edits
The rest don't matter. Hell you don't even need suggestions. Comments are really about all you actually need.
Anything I have to read that's more than 2-3 pages always gets printed. Especially if it's non-trivial.
It's a once/twice a week thing but nothing is as effective (I tried using my 2018 ipad/pencil but I just don't really like writing on it, the lack of surface resistance is wrong).
Otherwise you could stick it in <pre> / <code> tags in an html file, open it in a browser, and print from there.
Lots of options...
Usually I have IntelliJ open and it can print quite nicely.
Have you tried an ereader? I have one that's 8", has a frontlight, and runs full on Android, I use it after my no-tech nighttime threshold and during meetings. But I especially use it for any long form reading I have to do.
I have (a cheap Kobo something or other), but it was completely useless for handling most pdf documents and slow enough when navigating a document to get really annoying. It also didn't have any support for annotating or making comments. I've kind of had my eye on this: remarkable.com, but I can't quite bring myself to spend that much. What do you have/recommend?
Still not the perfect device, you can see some criticisms in the review above, but it's my favorite I've seen so far. Forgot to mention it has an SD card slot in additon to 16GB internal storage, compared to, say, the Kindle Voyage which has 2GB and that's it.
Still waiting on the dream of color eink monitors, but in the meantime this will do.
EDIT: It also has a togglable faster refresh mode, which doesn't clear the screen as well but is much easier to use for scrolling/panning around.
Then, when problems arise that were highlighted or predicted in the documentation, you can't just tell people "I told you so". But getting people to understand the flimsiness of slide presentations compared to documentation can be a slog.
Sometimes distillation and condensation can lead to more precise thinking too.
Western civilization has a bias toward the written, which has helped us produce analytical thinkers ("Reading maketh a full man, conference a ready man, and writing an exact man." - Francis Bacon). We tend to value precision in verbal expression and argumentation (disputation) as means of arriving at knowledge.
But I think we need to recognize that other cultures have other preferences that may be just as effective. From what I've observed, Japanese culture has a preference for the pictorial (Kanban is one such example) and it's amazing how much much they've achieved along those lines. I've worked with Japanese folks and their docs and slides tend to be diagram heavy (often beautifully so). Japanese product manuals also reflect their visual culture.
I don't think giving a full, narrative structured presentation beyond the capacity of a non-native speaker given effort. While certainly other communication-approaches exist in other cultures - as well as in our own, I don't think one can really say full narrative structure is Western specific.
Moreover, I'd say the intent of asking for a narrative argument is to require a significant cognitive load from anyone putting out an idea. You definitely don't get a "brainstorming" effect, where lots of idea appear at once, from requiring a full narrative description.
"Sometimes distillation and condensation can lead to more precise thinking too."
Indeed. But the principle is a well written long-form narrative consists of a sequence of precise, condensed statements and not merely blathering on.
It might seem unfair to ask non-native speaker to reach a level of long and precise utterances. But currently, American education is poor enough that writing a coherent narrative document would be quite hard for a fair portion of Americans.
To put it another way, my view is that
good visuals >> good writing > average writing >> average visuals
So I could certainly imagine a culture where the average visual presentation was good enough to make that the best choice.
But a well designed graphic can require as much work as a well written paragraph, and if the Japanese put all the care needed, then the end result will be very high quality.
The point is, it is not the nature of the media, but the mentality of the worker what guarantees results.
Often the presentations involve dumping literally all their graphs and text on the slide, and then literally reading from the slide.
(1) An acquisition memo justifying a functional/technical area (and specific target company) that we wanted to be able to move into due diligence with.
(2) A recommendation related to whether "Alexa" (the service) and "Echo" (the device) should have the same or different names.
In case you're wondering, the former was a 2-page and the latter, a 6-pager. In each case, the recommendation that we presented was accepted, the second after much more vigorous debate than the first. Jeff was initially strongly opposed to having two different names.
No one would read a 40-page document, but there were a few times when we ended up with 6-pagers that contained 20+ pages of detailed appendices.
I also believe that the culture of the document is a key success factor for Amazon (but that it can't just be cargo-culted into other organizations without a lot of buy-in).
I've been trying to find info about this practice (to use in my startup), but didnt find any.
Please take a read and let me know whether it's helpful.
You guys had the benefit of looking at your peers' work - what would be a good two pager that we can learn from ?
It's less a spec and more of, choose the tool that fits the job. A lot of these documents fit the overall structure of "high-level situation & recommendation; industry / product / customer context; more depth on recommendations considered; FAQ"
I don't have any examples, anymore (I left Amazon some years ago), but here are a couple of links that have reasonable takes on the structure and guidelines:
Bottom line: the purpose of the document is to drive a high-quality decision, so include what will help, and leave out anything extraneous. (I know, that's not very actionable.)
The other document, while seemingly a simple issue, had a lot of ramifications and would be hard to reverse once we made the decision. When he finished reading the doc, he initially disagreed that there should be two different names, thinking that it would be simpler from a branding and customer point of view to have only one. our position was that, although that would be true at launch, we needed to plan for success when Alexa, the service, would be available on many different types of hardware, even ones that were not made by Amazon, so we needed to do the work involved in keeping them separate. This type of decision was much more of a "one-way door" in Jeff's parlance.
Hope this makes sense.
FWIW, I do think that more and more "two-way door" decisions are being determined at Amazon using the narrative process, which can be very, very expensive.
At the start-up that I am at now, we are moving much more quickly by being using the narrative format thoughtfully.
As Dijkstra famously commented about writing, "You cannot sharpen a pencil with a blunt axe. Nor will 10 blunt axes suffice."
In my experience, one of the most common agendas for a meeting is "here is a document that the author is going to read to you."
Basically any global consultancy targeting c-suite ‘strategy’ advisement.
People have forgotten to write structured documents that logically layout your thoughts.
If you can understand a Powerpoint just from the graphics + bullets then it's done correctly. If it needs supplementary notes then send it back for rework.
This makes so much sense in context to Facebook and YouTube comments...
you literally get smarter from having to consider disparate perspectives. this is a lesson that's always stuck with me.
and it seems to uncover a gap elided in your conclusion:
> "Amazon's leadership makes better decisions than their competitors in part because they are routinely supplied with better arguments than their competitors."
i suspect better argument came not only from (an initial) concise writing by the narrator but the revision process incorporating other people's perspectives?
Then you can trace costs (and presumably savings) back as a dimension through the P&L?
I am only just coming to understand what they were seeing and why a long form essay would have been a much better way to get my information across. Now to convince my customers that a 6 page essay/report is much better than 60+ pages of graphs and filler.
I mean, they might be making better decisions, but they might just be making average decisions and riding the wave of technology due to having an online presence without brick-and-mortar stores to worry about.
Also, how do you disabuse folks who get their writing skills from Creative Fiction in college, and therefore write in a style more suited for dramatic effect than succinct communication? ie, how do you force actual "memo" writing?
> Also, how do you disabuse folks who get their writing skills from Creative Fiction in college, and therefore write in a style more suited for dramatic effect than succinct communication? ie, how do you force actual "memo" writing?
This is easier. If you are their manager, you hand them a couple of example documents that you believe to have been high-quality and effective, right when they join the team. Then, you read the first document that they write and return it to them marked up (edited) to meet your standards. They'll figure it out pretty quickly (or they won't, and then, to be honest, you've got a problem, because they'll have a hard time being successful at Amazon if they can't.)
So, for me, writing a 2-pager usually took 1-2 hours. After 1 week - 2 months of work getting to the point that I was ready to write. ;)
He suggests that a great memo takes a week or more. In my experience that's roughly right, though you'll often have been mulling over the problem for weeks before you actually start writing.
It doesn't fully cover the communication principles of the 6-pager. The missing parts are:
- 6 pages is the upper limit; the memo can be shorter
- The format is designed to drive the meeting structure by requiring attendees to read the memo in the first 10 minutes of a meeting, followed by discussion
- You can push extra information into the appendix if needed to convince those looking for more evidence
- The memo is self-sufficient as a unit of information, unlike a Powerpoint that relies on the presenter (or a video of them) to contextualize and connect the information
The basic thrust is to bring the discipline of scientific style article writing into office communications (and avoid Powerpoint anti-patterns in the process).
The essay will be discussed verbally too, but only after the reviewers have a chance to fully read the document and ruminate over it, typically for 30 minutes or more. The verbal discussion can elaborate on points made in the essay but isn't a substitute for them. This means that the quality of the writing needs to be high, and the hope is that high-quality writing facilitates high-quality thinking and presentation of ideas.
That's a flat-out lie itself.
A knowledge graph was acquired. Alexa - which, at this point, represents many thousands of years of engineering effort, was most certainly developed in-house.
Source: I wrote the 2-pager recommending the acquisition of said knowledge graph company.
Practically, many people wouldn't read it ("no time") or just skim it ("got the gist of it") and having a meaningful discussion becomes impossible.
The meeting then dissolves into a impromptu brainstorming session by all the people who haven't read it.
A decision is made to implement one of the newly brainstormed hare-brained ideas without taking the carefully thought out arguments and counterpoints in the memo into account.
In the end people congratulate each other on a "productive" meeting and the memo wanders into the trash, unread.
- There's disagreement... in which case, this is a needed conversation. It probably should happen before the meeting, but it's way better to have now than to kick down the road because sentence phrasing seemed beneath us.
- There's politics/personality issues... in which case, maybe the conversation isn't enjoyable, but that clash is going to happen at some point. If not this meeting, then the next.
One of the larger points going on in this thread is that articulating things forces reality checks—between you and your idea, between your idea and others' ideas, between the team's ideas and reality, etc.
I'd imagine the guy that started a company to sell books online has read many of them.
If you want to produce a bullet point powerpoint from the document then it should be possible to do it in a few hours. But the reverse isn't true.
Unsurprisingly non existent from Tufte was figuring out how to apply any of this to my current work culture.
There are important norms in Amazon's culture that support this method. Time is always set aside at the beginning of the meeting for people to read the paper. They know that no one will read it before-hand, so they make time in the schedule. Also, the main document is at most six pages, but you can supply an endless number of appendices. This gives people a place to put supporting information that feels too important to cut entirely.
I should add that the leadership should do it themselves and lead by example. When we introduced Agile the developers were the only ones who went to training while management continued as usual so our Agile quickly devolved into micromanagement. Same for code reviews. It's very important that the more experienced devs closely follow agreed-on coding styles.
That's an attitude of acceptance (is that the right word?) that I find inspiring.
I've felt that meetings would be more productive if the person presenting had to prepare some written material, and we all had to read it ahead of time. That way we have some shared base level of knowledge and the discussion can be done at a higher level.
Inevitably, some people don't read the doc. Some of them are honest and the presenter is nice and catches them up quickly. (If all of this information can be transferred in 1 minute, then why did I get a 5 page doc?). Or worse, people pretend they read it and didn't.
You could try to build some culture around "making it a requirement" (shaming them if they don't?) but, more often than not, the person who didn't read the materials is the biggest boss in the room, and enforcing requirements up a corporate org chart is a fool's errand.
So, someone at Amazon was like "fuck it", realizing that half the point of a meeting is just forcing people to work on something by putting them in a room together. And rather than complaining that that's kinda dumb (which it is) they just decided to increase the quality of work that happens in those meetings by setting aside 10 minute for reading.
This seems like it would apply to any meaningful culture change. Too often "buy in" is passive at best.
I think I'll steal your "absolutely unrelenting" phrase for next time I need to have a conversation with management about a real change.
Is this a method that brings agility only to large orgs ? If you had to do a startup, would you use the narrative method to develop a new feature/UI,etc ? Maybe you make it two pages rather than six...but still.
PS: Have any of you read all of Buffet's shareholder letters? Would those be worth reading from the beginning?
One of them is discussion over email (ie persuasive long form writing, combined with data driven evidence)
The other is of course ... voting
"... they mistakenly believe a high-standards, six-page memo can be written in one or two days or even a few hours, when really it might take a week or more!"
I think we need more details!
Obviously all of this works for Amazon so that's great, I wouldn't see any reason to change it, but it's probably worth thinking about a little.
I do not believe PowerPoint is inherently a bad format, nor do I believe that written is better, moreover, I think a lot can be lost in prose.
The reason I believe this is due to some military experience with SMEAC NATO orders format . This format can be used by Corporals on up to Generals, by all NATO forces such that a Polish recruit could sit in on a US General's Orders and effectively understand what is going on.
Aspects of SMEAC exist to enable tired and sleep deprived commanders and soldiers to create coherent and complete plans, and to ingest them as well.
Little things like: " You must always repeat the mission twice so that any squadies not paying attention have a chance to catch what it is they are meant to be doing."
At all levels, the Mission Objective (which is a specific format) is repeated twice. Always. The impetus is twofold: if well trained staff understand the mission objectives, then the rest is 'details' meaning, even if everything falls apart, training and skills can take over so the mission could be achieved. The 'say it twice' is essentially a double affirmation of the objective.
Once everyone is on this same wavelength, it's interesting to see how people can become operationally synchronized.
My feeling is that a SMEAC-like format for meetings would likely be ideal; something that requires a specific approach, with checklists that force product/technical etc. to contemplate various issues.
If this were to be done well, then it could be abbreviated into another format.
Another reason I'm just a little skeptical, is that every big movement has a series of behaviours and attitudes that help embolden the koolaid. Amazon started as a book selling company, so in a way, it kinds of makes sense for them to value the 'literary' in some way, and this odd behaviour (which actually does work) helps them differentiate their 'movement' in a material way and reinforce ostensible 'culture'.
It's probably worth some further analysis, and maybe some data points as well, because there are many things that make growing companies unique, I wonder if we should just assume those unique things are drivers or just arbitrarily correlated aspects.
Maybe a presentation for a live audience, and a dense paper for offline consumption is the optimal setting. The audience can remain engaged, and if an idea seems worthy, a deeper dive into the dense paper format occurs
Poor writing definitely makes it harder, and it turns out that the vast majority of people are poor writers, mainly because they don't practice. You might not have experienced high-quality business writing because it's so rare.
Powerpoint does have its uses; I've written and delivered lots of talks using powerpoint. But informing an audience about to make a high-stakes decision is not among them.
1. I'm now much more inclined to finish a project.
2. Writing about it forces me to truly understand the subject. There have been many times where things became clear only because I had to explain it to myself in words.
And you're right: the more I do it, the easier it becomes.
It's very satisfying.
I find blogging to be immensely helpful in crystalizing my thoughts as well as giving back.
I think the mix up between enlightenment/information vs decision making is the key here. You see presentations at Re:Invent all the time, because they are the former.
Leadership decision making definitely requires the nuance a standalone document can provide. Amazon takes it a step ahead by imposing a condense requirement: now you need to write well too.
RE other comments about fluffing / buzzwords, you probably are highly misjudging the level of intelligence of this particular audience. IOW I would love to try and see someone try to push such a doc with Jeff et al :)
Because of its audience and goals it's necessarily less technical and more essay-like than a typical s-team memo. For obvious reasons, I can't link to any of those.
An example that's close and is in the public domain is Jacobsen's TCP slow start paper: https://ee.lbl.gov/papers/congavoid.pdf. He's advocating a specific change in the TCP protocol and marshalls evidence beautifully to make his argument.
"may be because customers have such easy access to more information than ever before – in only a few seconds and with a couple taps on their phones, customers can read reviews, compare prices from multiple retailers, see whether something’s in stock, find out how fast it will ship or be available for pick-up, and more."
Everything after the clause "... then ever before" is superfluous. Shareholders know what sort of information customers can obtain, and how. He implies that with the weak "and more" at the end. But too late, he has already wasted the reader's time.
I'm not particularly impressed by that writing style, it reminds me of 16 year olds trying to impress me with their verbose history essays.
The idea of business writing is to COMMUNICATE. If the reader reads an entire paragraph and hasn't learned anything new then the author has failed. If the reader needs to use a highlighter to pick-out pertinent information from a sea of words, the author has failed.