"Writing is nature's way of letting you know how sloppy your thinking is." -Dick Guindon, via Leslie Lamport
"Writing is nature's way of letting you know how sloppy your thinking is." -Dick Guindon, via Leslie Lamport
Indeed!
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.
FWIW, some four years ago I wrote this for this "bug filing recommendations"[1] 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.
[1] https://wiki.openstack.org/wiki/BugFilingRecommendations
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.
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.
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.
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.
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.
Making the presenter bring everything needed to have a distraction free conversation is a feature, not a bug.
Anything I have to read that's more than 2-3 pages always gets printed. Especially if it's non-trivial.
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.
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.
Any other rules of thumb for people who are trying to adopt this ?
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.
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) - Comments - 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.
People have forgotten to write structured documents that logically layout your thoughts.
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.
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.
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.
As Dijkstra famously commented about writing, "You cannot sharpen a pencil with a blunt axe. Nor will 10 blunt axes suffice."
Two examples:
(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.
https://medium.com/@sib1013/writing-docs-at-amazon-e02580861...
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:
https://www.anecdote.com/2018/05/amazons-six-page-narrative-...
https://use-cases.org/2018/01/03/the-evil-genius-of-the-amaz...
https://www.geekwire.com/2017/prepared-6-page-memo-geekwire-...
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.
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.
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.
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.
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.
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?
https://medium.com/@sib1013/writing-docs-at-amazon-e02580861...
> 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. ;)
https://www.sec.gov/Archives/edgar/data/1018724/000119312518...
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.
https://www.linkedin.com/pulse/beauty-amazons-6-pager-brad-p...
https://www.anecdote.com/2018/05/amazons-six-page-narrative-...
https://medium.com/@sib1013/writing-docs-at-amazon-e02580861...