I recently asked for a simple architecture design for a small software project.
What I got back was a long document full of database types, framework terminology, implementation details, and raw diagram syntax.
Technically, the information was there, but I had to work far too hard to understand it.
This is becoming a common problem in tech: people are producing AI-generated documentation without thinking about the fact that another human being is supposed to read it.
Documentation is not a data dump. If I ask for an architecture document, I want to understand the system: the main components, how they connect, the important decisions, the risks, and the tradeoffs.
I usually do not need to know immediately whether the max field length is 50 chars or whether some relationship uses a specific ORM syntax.
Now with AI you can generate 30 page documentation in a few seconds. But reading those 30 pages still takes time.
So now we have a strange workflow: AI generates the document -> A human receives it -> The human asks ChatGPT to explain what the document actually means.
At that point, something has gone wrong.
Using AI to draft documentation is completely reasonable. Sending the first generated output without reviewing it is not.
If your name is on a document, you should read it, simplify it, remove irrelevant details, fix unclear language, and make sure it matches the audience.
Good documentation is not measured by how much information it contains but by how quickly the reader can understand the important parts.
Simplicity often reflects understanding. If you understand a system well, you can usually explain it clearly. You know what matters and what does not.
If a simple system requires 30 pages of unexplained technical detail, the problem is not the documentation, it’s that nobody stopped to think.
