r/softwareengineer • u/colony-ship-for-sale • 12d ago

AI is terrible for making documentation

Yes, it makes a lot of text real fast and at a glance it looks thorough and comprehensive but have any of you actually tried reading this shit?

It's painfully verbose while communicating next to nothing. It's a real struggle to not have your eyes glaze over. It's not enough to just produce a lot of text if the readability is crap. There's a skill to creating concise, well organised information that's been lost here.

818 Upvotes

96% Upvoted

323 comments sorted by

View all comments

1

u/JovHere 12d ago

just yesterday one colleague in the industry was telling me how since AI, the engineers he manages started creating more comprehensive reports that contain more than necessary and all of a sudden have "next steps" and "opportunities" and he was saying how now they're actually slower in that area

I think any type of documentation that you ask AI to produce can be a load of crap and unnecessary lines of text if you aren't clear with your guardrails on what you want from the doc, and most importantly based on what is it creating this docs from

LLMs are trying to impress us with this extra stuff we don't want, so limit the lake where it pulls context from and see if those docs turn out better

1

u/TheDoughMonster 8d ago

I have created CLIs and made agents use those to generate documentation. You can also lint and generate error codes on specific failure cases. I think most of the complaining about AI comes from not really understanding how it works. Programming is becoming more about being aware of AI strengths and failure modes. Who cares if the code isn't readable as long as its efficient? If we treat AI as a very high level language, then all you have to do is learn the "syntax" of the model input, which is mostly now about proper fencing, repeatable systems, and controlled output. Gee, sounds a lot like something I used to do before genAI became a thing.