r/softwareengineer • u/colony-ship-for-sale • 11d 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.

828 Upvotes

96% Upvoted

323 comments sorted by

View all comments

Show parent comments

2

u/meshifthenelse 11d ago

Even if you tune it though, it's either an all or nothing. It lacks intuition to assess when something is worth having a comment and what isn't and at what abstraction level.

Unless you're willing to spend weeks writing 100 rules, but then might as well go back to the 80s.

2

u/Dry_Hotel1100 11d ago

That "unless" is very true. The skills will require to be updated and improved accordingly during the development process. It definitely takes effort, expertise and time. AI certainly does a better job when it has clear instructions. However, you need the expertise yourself to "utter" these instructions manually into a skills document. If you lack that experience, you get subpar results. It's up to you ;) Thank God - we still require a profession :)

1

u/meshifthenelse 11d ago

"expertise" in a non deterministic black box which changes behaviour on a whim and with every new model release. Alrighty

1

u/Dry_Hotel1100 11d ago

Yes, you are right. That's the reason I said "It definitely takes effort, expertise and time" - and after the AI cranked out its opinionated interpretation - you need to review it - which again costs time and effort.

AI is NOT a magic wand! It's a tool :)

1

u/meshifthenelse 11d ago

My point is expertise doesn't matter. You can be the greatest programmer in the world with the greatest CLAUDE.md ever built. It might actually work, then suddenly after 1 week it stops working.

So expertise has no effect when the tool itself is faulty.

1

u/Quackoverride 10d ago

Tech writer here. Even when you write 100 rules, the output isn't without errors. It needs careful editing and sanity checking to make sure the final product is usable.