Remix.run Logo
embedding-shape 9 hours ago

> no one reads it. [... ] they seem disillusioned

Regardless of reasons they tell you, if no one reads your documentation, then it isn't good enough. Good documentation gets read, as long as it is good. It sounds to me like you're disillusioned, if you're not responding to the feedback, even if you sometimes have to look through the reasons people tell you on the surface.

saulpw 9 hours ago | parent | next [-]

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.

krisoft 9 hours ago | parent | prev [-]

Maybe. But also if the thing was not documented for years, then maybe the users learned how to use it without documentation? Or at least how to get what they need done.

People won't read documentation of something they already know (or think they know).