alt Hacker NewsI find AI is great at documenting code. It's a description of what the code does and how to use it - all that matters is that it's correct and easy to read, which it almost certainly will be in my experience.
Replies
> all that matters is that it's correct and easy to read
Absolutely disagree. A lot of the best docs I've read feel more personal, and have little extra touches like telling the reader which sections to skip or to spend more time in depending on what your background is.
Formatting and layout matters too. Docs sites with messy navigation and sidenotes all over the place might be "easy to read" if you can focus on only looking at one thing, but when you try to read the whole thing, you just get a bunch of extra noise that could've been left out.
Documentation is needed for intent. For everything else you could just read the code. With well-written code, “what the code does and how to use it” should be clear.
I have quite a different take on that. As much as most people view documentation as a chore, there is value in it.
See it as code review, reflection, getting a birds eye view.
When I document my code, I often stop in between, and think: That implementation detail doesn't make sense/is over convoluted/can be simplified/seems to be lacking sanity check etc…
There is also the art of subtly injecting humor in it, with, e.g. code examples.