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. :)
When I was younger, people told me I could read faster if I did speedreading. You could just sort of scan over what you were reading, and get the same sort of understanding in a fraction of the time.
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.
(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. :)
When I was younger, people told me I could read faster if I did speedreading. You could just sort of scan over what you were reading, and get the same sort of understanding in a fraction of the time.
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.
[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.