Remix.run Logo
saulpw 9 hours ago

There are many reasons people might not read your documentation, and "it isn't good enough" is only one of them. To wit:

   - they don't know about it
   - they can't find it when they need it
   - they just don't read documentation (quite common)
   - they've been burned by stale docs in the past
and I'm sure other reasons besides.

And while you're right, that sometimes/usually/always the documentation isn't good enough, it's a fallacy to think that the person who has the information needed, has the skill to write docs that are good enough for people to read. And if they have the skill, they don't have the time to apply it sufficiently.

Let's face it: good docs aren't valued. Not by the organization structurally, and not by the individuals within the organization. You may say that you value it, but I bet that if someone offered to document whatever code or process to your 'good enough' level, and it would take a month to do, as a manager you would tell them to take less time (i.e. create bad documentation) and get to something more important.