undefined

points

[-]

I 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.

by b2ccb28 hours ago|

parent|

[-]

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.

by elxr4 hours ago|

parent|

prev|

[-]

> 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.

by archagon10 hours ago|

parent|

prev|

[-]

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.