3 ms·

If your customers or colleagues are asking questions answered by your documentation, it's often a good sign your documentation has some challenges: dense; intim

If your customers or colleagues are asking questions answered by your documentation, it's often a good sign your documentation has some challenges: dense; intimidating; inaccessible; or not easy to search for the specific information you want. Take this valuable signal as a gift, letting you know there is an opportunity to improve the documentation. You could become known as a helpful person, rather than a maybe-efficient, antisocial loner. If your documentation is generated (by script, tool, or AI), rather than written by a person, this goes double.

bluGill 2mo ago
Most of the problem is people don't know to look for it and so don't try. By asking them to help improve it that means I'm not shaming them for not looking at it and so they are more likely to read it. Also once in a while I get useful suggestions for improvement and so my documentation is now the best on the project, perhaps company (this is a very low bar)
prepend 2mo ago
> good sign your documentation has some challenges: dense; intimidating; inaccessible; or not easy to search for the specific information you want Of course it does. And it’s not “my documentation” it’s ours. And everyone is responsible for improving it. It’s not about pointing out that documentation sucks, it’s about working to improve it. I don’t have a documentarian on my team. No one’s main job is to write docs. So we all get to help each other by gradually improving the docs. And if I help someone with something not in the docs then the recipient gets to include that missing info into the docs to help the next person. We also added a hat for a rotating role called “Benevolent Documentation Czar for the Quarter” where that person gets to explicitly improve team docs. Maybe like 5% of their time.
infamouscow 2mo ago
So how exactly are you supposed to distinguish needing to improve the documentation from the fact that half the population—through no fault of their own—might be fundemenetally incapable of understanding the documentation? You can only polish something so much. Without a limiting principle this becomes unfalsifiable and an endless time sink.
- bluGill 2mo ago
  As a general rule you cannot get a job working in my area without fluency in English. Probably the majority of the people who work with my code have English as a second language (I work with people in Germany, India, Mexico, and Brazil that I know of), but English is a requirement to work with my area. There are probably people in sales and support areas who don't speak English, but if they need to work with me they need a translator. (I'm lucky to be a native English speaker, but there is no reason I couldn't learn a different language)
- ImPostingOnHN 2mo ago
  if the person is incapable of, or unwilling to, read documentation which you think they should, you can ask them honestly about it, or ask your manager about it if management feels this person is unqualified to be in their job, they can take care of the issue "rtfm" or the AI equivalent is being snarky while dodging the issue that you should just talk about, which is that you think this person is asking you too many questions

bluGill 2mo ago

Most of the problem is people don't know to look for it and so don't try. By asking them to help improve it that means I'm not shaming them for not looking at it and so they are more likely to read it. Also once in a while I get useful suggestions for improvement and so my documentation is now the best on the project, perhaps company (this is a very low bar)

prepend 2mo ago

> good sign your documentation has some challenges: dense; intimidating; inaccessible; or not easy to search for the specific information you want Of course it does. And it’s not “my documentation” it’s ours. And everyone is responsible for improving it. It’s not about pointing out that documentation sucks, it’s about working to improve it. I don’t have a documentarian on my team. No one’s main job is to write docs. So we all get to help each other by gradually improving the docs. And if I help someone with something not in the docs then the recipient gets to include that missing info into the docs to help the next person. We also added a hat for a rotating role called “Benevolent Documentation Czar for the Quarter” where that person gets to explicitly improve team docs. Maybe like 5% of their time.

infamouscow 2mo ago

So how exactly are you supposed to distinguish needing to improve the documentation from the fact that half the population—through no fault of their own—might be fundemenetally incapable of understanding the documentation? You can only polish something so much. Without a limiting principle this becomes unfalsifiable and an endless time sink.

bluGill 2mo ago
As a general rule you cannot get a job working in my area without fluency in English. Probably the majority of the people who work with my code have English as a second language (I work with people in Germany, India, Mexico, and Brazil that I know of), but English is a requirement to work with my area. There are probably people in sales and support areas who don't speak English, but if they need to work with me they need a translator. (I'm lucky to be a native English speaker, but there is no reason I couldn't learn a different language)
ImPostingOnHN 2mo ago
if the person is incapable of, or unwilling to, read documentation which you think they should, you can ask them honestly about it, or ask your manager about it if management feels this person is unqualified to be in their job, they can take care of the issue "rtfm" or the AI equivalent is being snarky while dodging the issue that you should just talk about, which is that you think this person is asking you too many questions