4 ms·

The Document Culture of Amazon (2021)

23 points by Tomte 2y ago

mitchbob 2y ago
Discussed earlier (2021, 215 comments): https://news.ycombinator.com/item?id=27545331 https://news.ycombinator.com/item?id=27545331
deleted 2y ago
[deleted]
huntaub 2y ago
It's interesting, after my time at Amazon (8 years) -- I struggled to visualize decisions without a document, because you get so used to reviewing things in that way. However, it's EXTREMELY heavy-handed. People will give you comments on the structure of your document (to "raise the bar") instead of the content of the document, and often you can't get documents reviewed until they are aesthetically in the right place for people to digest them. Ultimately, I think it makes sense when you're at a large organization with high attrition (such that you need to keep track of all of the decisions which are made), but otherwise, it's probably not worth it to do a formal document writing process.
- qqtt 2y ago
  I don’t think that is specific to Amazon. If anything I think the whole paradigm of “over analyzing communications with vacuous update suggestions that don’t matter” is probably the most consistent thread I’ve found in all of corporate America. I’ll never forget early in my career we had huddled around a coworkers computer with our entire team including senior manager writing an email to a VP and the senior manager was making punctuation and the most inane wording updates you can imagine. I once thought there is no way the absurdity of the cost to benefit of that situation would be topped, but how naive I was - turns out generally companies seemingly can’t avoid that kind of atmosphere.
  - bravetraveler 2y ago
    The songs demand a camp fire
- yazaddaruvala 2y ago
  The real benefit of doc writing isn’t for decision making it’s for education. It allows everyone at Amazon to evaluate the author’s ability to refine their “chain of thought”. The nice side effect is the author taking 10x more time to save 10x L+1 and L+2 leaders (ie more expensive people) from spending that same time trying to understand it.
  - euroderf 2y ago
    > The nice side effect is the author taking 10x more time to save 10x L+1 and L+2 leaders (ie more expensive people) from spending that same time trying to understand it. IMHO this is analogous to most of the economic justification for not being sucky at documentation. When you apply this analysis to the user-facing side, an hour of documentation can save hundreds of hours of user thrashing. This is something that I would assume is intuitive, but under the capitalist mode of software development, it seems to be an uphill fight to get the economic rationale into management's heads. There are of course exceptions, and they stand out in excellence. When you shortchange documentation, you're externalizing costs that shared efficiencies say should be internalized. Kind of like dumping sewage in the lake, or driving on leaded gas.
  - zaphirplane 2y ago
    Yet there are more successful companies than Amazon or as successful that don’t use this approach. That clearly shows it’s a cultural or quirky thing, otherwise there would be a clear correlation between a company’s success and the doc culture
alphazard 2y ago
I've seen mixed results with reading the document during the meeting. It can help with people not having read the document. But people read at different paces, and the people who put off or avoid reading before the meeting are doing so because they are slow readers or have poor comprehension or retention. Reading has a high opportunity cost for them, so they avoid it. Asking them to read during the meeting usually results in a performance, they skim or get through as much as they can until people start saying they are done, and then they don't want to hold things up so they also announce they are done. This can happen with all slow readers, even those who would have high comprehension with multiple passes or at their own speed. The other issue is the asymmetry of effort, which the author alludes to with "no doc => doesn't happen". Proposals require writing, but criticisms can be made verbally. You would expect a lot of the feedback to actually make the proposal worse because the proposal has been through a few write-edit cycles and the feedback is generated on-the-spot during the meeting within minutes of first reading the proposal. If critics don't also have to write then feedback becomes a game of politics. If you ask people to give feedback on something without time to think, you will get noise. No one wants to appear bad at reading in front of their peers.
- kixiQu 2y ago
  > the people who put off or avoid reading before the meeting are doing so because they are slow readers or have poor comprehension or retention. Reading has a high opportunity cost for them, so they avoid it. This sounds like a description of people making bad choices at their jobs despite an obvious correct path (don't put off or avoid prereading). If they'd have high comprehension with multiple passes and at their own speed, it's their responsibility to figure that out and take those. Correspondingly they absolutely have the freedom to hunt down the meeting scheduler if the latter hasn't provided the doc enough in advance for this. (There are a lot of ways that I'd say Amazon culture is unaccommodating of difference, but this isn't one) > Proposals require writing, but criticisms can be made verbally. IME, anything that a critic doesn't insist get captured (with an action item and typically their name attached to the feedback) is treated as wind in leaves.
- ThrowawayR2 2y ago
  > "...slow readers or have poor comprehension or retention..." Our entire profession is based on working with text intensively, whether code or docs or specs. Anybody with these difficulties that aren't making the effort to compensate for them isn't going to last long, particularly at Amazon or another FAANG.
deleted 2y ago
[deleted]

23 points by Tomte 2y ago

Discussed earlier (2021, 215 comments): https://news.ycombinator.com/item?id=27545331 https://news.ycombinator.com/item?id=27545331

deleted 2y ago

[deleted]

huntaub 2y ago

It's interesting, after my time at Amazon (8 years) -- I struggled to visualize decisions without a document, because you get so used to reviewing things in that way. However, it's EXTREMELY heavy-handed. People will give you comments on the structure of your document (to "raise the bar") instead of the content of the document, and often you can't get documents reviewed until they are aesthetically in the right place for people to digest them. Ultimately, I think it makes sense when you're at a large organization with high attrition (such that you need to keep track of all of the decisions which are made), but otherwise, it's probably not worth it to do a formal document writing process.

qqtt 2y ago
I don’t think that is specific to Amazon. If anything I think the whole paradigm of “over analyzing communications with vacuous update suggestions that don’t matter” is probably the most consistent thread I’ve found in all of corporate America. I’ll never forget early in my career we had huddled around a coworkers computer with our entire team including senior manager writing an email to a VP and the senior manager was making punctuation and the most inane wording updates you can imagine. I once thought there is no way the absurdity of the cost to benefit of that situation would be topped, but how naive I was - turns out generally companies seemingly can’t avoid that kind of atmosphere.
- bravetraveler 2y ago
  The songs demand a camp fire
yazaddaruvala 2y ago
The real benefit of doc writing isn’t for decision making it’s for education. It allows everyone at Amazon to evaluate the author’s ability to refine their “chain of thought”. The nice side effect is the author taking 10x more time to save 10x L+1 and L+2 leaders (ie more expensive people) from spending that same time trying to understand it.
- euroderf 2y ago
  > The nice side effect is the author taking 10x more time to save 10x L+1 and L+2 leaders (ie more expensive people) from spending that same time trying to understand it. IMHO this is analogous to most of the economic justification for not being sucky at documentation. When you apply this analysis to the user-facing side, an hour of documentation can save hundreds of hours of user thrashing. This is something that I would assume is intuitive, but under the capitalist mode of software development, it seems to be an uphill fight to get the economic rationale into management's heads. There are of course exceptions, and they stand out in excellence. When you shortchange documentation, you're externalizing costs that shared efficiencies say should be internalized. Kind of like dumping sewage in the lake, or driving on leaded gas.
- zaphirplane 2y ago
  Yet there are more successful companies than Amazon or as successful that don’t use this approach. That clearly shows it’s a cultural or quirky thing, otherwise there would be a clear correlation between a company’s success and the doc culture

alphazard 2y ago

I've seen mixed results with reading the document during the meeting. It can help with people not having read the document. But people read at different paces, and the people who put off or avoid reading before the meeting are doing so because they are slow readers or have poor comprehension or retention. Reading has a high opportunity cost for them, so they avoid it. Asking them to read during the meeting usually results in a performance, they skim or get through as much as they can until people start saying they are done, and then they don't want to hold things up so they also announce they are done. This can happen with all slow readers, even those who would have high comprehension with multiple passes or at their own speed. The other issue is the asymmetry of effort, which the author alludes to with "no doc => doesn't happen". Proposals require writing, but criticisms can be made verbally. You would expect a lot of the feedback to actually make the proposal worse because the proposal has been through a few write-edit cycles and the feedback is generated on-the-spot during the meeting within minutes of first reading the proposal. If critics don't also have to write then feedback becomes a game of politics. If you ask people to give feedback on something without time to think, you will get noise. No one wants to appear bad at reading in front of their peers.

kixiQu 2y ago
> the people who put off or avoid reading before the meeting are doing so because they are slow readers or have poor comprehension or retention. Reading has a high opportunity cost for them, so they avoid it. This sounds like a description of people making bad choices at their jobs despite an obvious correct path (don't put off or avoid prereading). If they'd have high comprehension with multiple passes and at their own speed, it's their responsibility to figure that out and take those. Correspondingly they absolutely have the freedom to hunt down the meeting scheduler if the latter hasn't provided the doc enough in advance for this. (There are a lot of ways that I'd say Amazon culture is unaccommodating of difference, but this isn't one) > Proposals require writing, but criticisms can be made verbally. IME, anything that a critic doesn't insist get captured (with an action item and typically their name attached to the feedback) is treated as wind in leaves.
ThrowawayR2 2y ago
> "...slow readers or have poor comprehension or retention..." Our entire profession is based on working with text intensively, whether code or docs or specs. Anybody with these difficulties that aren't making the effort to compensate for them isn't going to last long, particularly at Amazon or another FAANG.

deleted 2y ago

[deleted]