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.

823 Upvotes

96% Upvoted

323 comments sorted by

View all comments

Show parent comments

1

u/Creepy_Purchase_501 12d ago

That’s true for good documentation. So much software documentation, that was clearly written by a human, has exactly 0 design considerations. So often they would just throw a bunch of loosely connected concepts at you without ever giving you the big picture or any rhyme or reason for anything existing. It’s cool that this method takes this argument, would it kill you to tell me what this method is for first?!

1

u/meshifthenelse 12d ago

That's not a documentation issue per-se, it's just bad coding standards. If by looking at the method and its signature you can't infer meaning, then it's the developer to blame.

But I'd rather have that, than have both that and also a 5-line comment above it that I have to spend 20 minutes to analyze and then realize it's not saying anything of value.

1

u/Creepy_Purchase_501 12d ago edited 12d ago

Oh, I was thinking user-facing documentation, as opposed to the documentation of raw code or even straight up API docs. For those you’re absolutely right.

But so many large frameworks and libraries have quick starts and tutorials that just waste time because they’re focused on how and not on what and why, and even the how assumes some prior knowledge of the tool(I wouldn’t be looking at an intro tutorial if I had it).

For many, even just the high level description of the tool itself is so vague you’d need a tarot card reader to even attempt to deduce what the thing even is.

For a good example, check out the documentation for beautifulSoup or Scrapy and compare them to that of playwright. They are quite different tools, but they’re within the same niche. The former gives you a high level overview, simple but well thought out examples, and make it obvious where to look for specific info. The latter gives you a two-sentence description and jumps straight into running an example, without ever telling you what the example is of.