Great resource. While writing is clearly an important task, I would like to hear opinions on making others read the manual. I'm at a big org and not only do other Devs not read the help I've written, they just shoot out messages asking for a session to explain exactly what's in the document. This is true even if I've recorded a demo video. How do you tackle this problem?
This is a good question. I think there are a number of things to think about.
* Are your docs organised in such a way that it's easy to find what you're looking for? Do you have search? Does the search work for people? Do you have analytics that can help you answer these questions?
* One strategy is to push people into public forums. Not everyone will be on board with this, but it doesn't hurt to ask 'hey, this is a fairly common question, would you mind asking it in a public channel so that there's a record of it for others?'
* Say no. Hard to do, but ultimately, if you think your docs are bulletproof, gently say no to direct requests for help. Something like 'Hey, we've written some docs that help with this exact thing. Please have a read, and then I'm happy to answer any questions you have after that'.
* Take questions as opportunities to improve tooling. If something gets asked often enough, can you avoid it being asked again by improving tooling in some way? Can you adjust error messages, link to docs in your error messages, word help text in a clearer way?
Ultimately, you interpret this issue in two ways. You can interpret it as 'people are stupid and/or lazy and there's nothing I can do about it'. Or you can interpret it as something to be improved in your docs/tooling/communication/processes. It's almost always the latter, and even if it isn't, treating it that way will improve your docs for everyone.
2 comments
[ 3.0 ms ] story [ 16.6 ms ] thread* Are your docs organised in such a way that it's easy to find what you're looking for? Do you have search? Does the search work for people? Do you have analytics that can help you answer these questions? * One strategy is to push people into public forums. Not everyone will be on board with this, but it doesn't hurt to ask 'hey, this is a fairly common question, would you mind asking it in a public channel so that there's a record of it for others?' * Say no. Hard to do, but ultimately, if you think your docs are bulletproof, gently say no to direct requests for help. Something like 'Hey, we've written some docs that help with this exact thing. Please have a read, and then I'm happy to answer any questions you have after that'. * Take questions as opportunities to improve tooling. If something gets asked often enough, can you avoid it being asked again by improving tooling in some way? Can you adjust error messages, link to docs in your error messages, word help text in a clearer way?
Ultimately, you interpret this issue in two ways. You can interpret it as 'people are stupid and/or lazy and there's nothing I can do about it'. Or you can interpret it as something to be improved in your docs/tooling/communication/processes. It's almost always the latter, and even if it isn't, treating it that way will improve your docs for everyone.