pradn
4 hours ago
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. :)
XajniN
2 hours ago
[dead]