3 ms·

Lots of people, myself included, read documentation.

• ks2048 2y ago
  Ditto. The problem is self-reinforcing: people don’t read docs because the docs are bad… we don’t spend time on docs because no one reads them…
  • sshine 2y ago
    Not only is it self-reinforcing: It is inevitable because some competent programmers deliberately don’t comment their code, read comments, or delete other people’s comments when they are stale.
  • sshine 2y ago
    > The problem is self-reinforcing: people don’t read docs because the docs are bad… we don’t spend time on docs because no one reads them… I don't get discouraged from writing docs because nobody reads them. I'll read them. But I do experience another similar self-reinforcing problem: If other people don't read or update my docs, the docs begin to lie.
• sshine 2y ago
  I personally read and write a lot. I track things in git messages by cross-referencing issues, and I comment my code. But my point is: when you have a cultural divide among competent programmers on whether to comment, not commenting game-theoretically wins, because the outcome where you have comments that get updated some percent of the time is worse than not having those comments. Instead, embed what you want to say in a comment in the code itself, or in a test. Documents your libraries and APIs if they are used by people outside your team.