The Death of Amazon's Writing Culture
alifeengineered.substack.com
alifeengineered.substack.com
1) It's easy to generate very long docs that explore every conditional, etc. It is probably better overall, because more edge cases are being caught. But, the docs tend to be very long, and often at a lower abstraction level than appropriate for a design doc. At the limit, why not just put all the code in the design doc, too? It's rarely necessary. Though, when the thing we're focusing on is an API, it is appropriate to put the API service proto diff in the design doc...
2) They're harder to read, often for easily discernable reasons. They love doing the "bullet colon sentence" pattern, which often just means you're reading a concept twice. Sometimes, it helps. But I can't help but distrust that pattern more just because its so obviously AI generated. A more pernicious problem is the AI using phrases that are technically correct, but not part of our verbal culture. An example is using "observability workloads" instead of "probers" or "CL submission strata" instead of "CL submission order". Perhaps a Skill and an obedient AI can make these particular problems go away. Perhaps there needs to be a "preferred vocabulary" dictionary distilled from all the teams' docs...
If I generate code or text with AI, I have been adding a bit of hand-written text that tells people what exactly I verified. Like "I've read all the words in this comment", or "I cross checked this data with other similar metrics at X". The trust you get from human validation is the scarce thing now, not the output itself.
I was embarrassed to blurt out factoids based on quick AI-based analysis that turned out to be incomplete at later, deeper inspection. So I've stopped doing that. :)
But I could/would never do it, because I would lose important details and comprehension.
What is really strange is that in the age of AI I do what I would never have done years ago.
I just sort of scan the obvious title name, the obvious section names, and low-density inconsequential text and don't miss much and do not read.
I just sort of jump my eyes down the page and that's how I read (or absorb) AI text.
I don't really like it.
loosely related in personal reading, I used to read kindle books and I was just annoyed by the self-published books with typos. Now I've accepted it because it seems to me like it's a mark of something written by humans.
I read some AI written books and they seem to have this boring less dense quality, with a sort of structure including a summation of the story so far at the end of every chapter.
I don't really like that either.
The writing culture is very real, and when done correctly is fantastic. But it worked because it is harder to write than it is to get up in front of bullet points and waffle out a one hour presentation.
Writing is hard because it really forces you to think. Clearly articulating thoughts means clearly thinking to begin with.
I suspect the lower level doc reviews are going to be filled with a lot of AI slop, but I would expect that presenting a sloppy document to an exec would be met with a "what is this" a swift exit from the room just as it always has.
IMO, this is exactly the point of the one-pager, the two-pager, the six-pager, etc…. You have to distill down what you’re talking about in simple enough terms that you can get your point across in such a brief document. That’s why PowerPoint was outlawed.
These writing methods really force you to fully understand the material well enough that you can simplify it enough and still have the result stand up to very critical exposure.
There’s nothing in the world (that I know of) to make your pants browner faster than knowing your document is going to be examined by an Executive VP at Amazon who clawed his way up from the trenches over a period of twenty years.