The problems I see with AI-generated, or heavily-AI assisted technical design docs in my team:
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. :)
(Disclosure: I was at AMZN for 10 years, left at the start of this year)
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.
I ran into this trying to find a good book on modern python. There are tons of releases on very specific python versions, and when I dug into it they were all written by AI and reviewed poorly. It's honestly just getting hard to find good technical books in certain areas because there's so much nonsense going on in the space.
The problems I see with AI-generated, or heavily-AI assisted technical design docs in my team:
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. :)
[dead]
(Disclosure: I was at AMZN for 10 years, left at the start of this year)
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.
I ran into this trying to find a good book on modern python. There are tons of releases on very specific python versions, and when I dug into it they were all written by AI and reviewed poorly. It's honestly just getting hard to find good technical books in certain areas because there's so much nonsense going on in the space.