The key is not to focus on “what” needs documenting, but “how” someone will use your documentation: to get set up, to consume an api, to modify behavior, etc. If you write with the goal to help someone with X problem do Y to solve it, the empathy problem becomes a bit more tractable.
I see this advice a lot, and I think it's making the problem worse.
The most common form of bad documentation I come across is simply documentation with pieces missing: it uses terms without defining them, it tells you what problem an option is intended to solve but doesn't say what effect it actually has, and so on.
One possible cause is the "empathy" theory: the author missed that bit out because they assumed the reader already knew it. But I think it's more common that the author just did a half-way job, because we don't have a documentation culture that takes being complete and correct as the minimum baseline.
If that's the case, I think the advice authors need is to _not_ spend so much time thinking about what their reader is trying to do, and spend more time thinking "is what I've written complete?".
After reading this, I wrote a blog post. It will be part of the series, but probably released in a few days. I have so many ideas to cover! Now it's past midnight though, so I should probably get some sleep!
Sure. But they can’t know whether it’s complete without answering the question, “have I given the reader all the info they’d need to solve their problem?”
Edit: grammar
