8 ms·
This is the problem with any kind of documentation; while you can write the highest quality, meticulous, most obvious and clearest prose, it's moot if nobody re
by Cthulhu_ 3y ago
This is the problem with any kind of documentation; while you can write the highest quality, meticulous, most obvious and clearest prose, it's moot if nobody reads it.
And nobody reads it because there's so much of it and there's no clear starting point. People just want the summary of what they're looking for.
I started to learn Java almost 20 years ago, we had a text book and everything. After the first two chapters, I learned how to google and instead of reading everything, just find what I need. I never went in-depth with reading because... it's mostly useless knowledge that quickly becomes outdated.
- theamk 3y agoNah, we have documentation with a clear starting point - there is index page with most common topics, "new user" page with links to what new user should read, and some error messages actually contain wiki links to pages with instructions. And yet we still have people who don't read documentation.
- mostlylurks 3y agoWith commit messages, there is a very clear starting point: the commit message for the commit that last touched the line of code you're looking at with git blame, which is my standard solution for finding out the reasoning behind any piece of code I don't quite understand. Only works for projects that don't destroy their history with squashes or otherwise write uninsightful commit messages (e.g. "fix bug").