Inspired by this post about the XY Problem, let’s talk about how users can approach documentation from a totally unhelpful angle.

The gist of the XY Problem is that “I was doing X and it’s not working” is not the same as “I was trying to solve Y; was X the right way to do it? If not X, then what?” For example, “Can someone help me rebase my Git branch?” assumes you need a rebase; “Can someone help me get my local branch to where I can work with it again” makes no such assumptions. And that theoretical someone may help you with less drastic measures.

As a technical writer, you should remember that users aren’t always looking for answers to the right questions, either. There could be a very, very simple way to do X. But the user may have assumed they need to use Convoluted Method Y, and they’re searching your docs for an explanation of how to use Y, not how to do X. And they’re getting angry, because it’s an undocumented path.

The reason it’s undocumented is that it’s immensely difficult to predict human creativity in problem solving – the one thing that still makes us look better than robots. You can guess some of the cases, especially the ones where users have expectations rather than creativity. For example, if you know your competitors normally use Y, you can assume users will try that first. But true human ingenuity is unpredictable and often indistinguishable from stupidity (so perhaps if your engineers say “no one would ever be dumb enough to try that” you can be sure that users will absolutely try that).

My only advice, therefore, is to keep an eye on incoming feedback, see where most of your users stumble, and explicitly document “this is a bad idea; please try this instead”. Don’t spend too much time trying to guess at this; you will never be as creative as a software engineer with a tight deadline and a six pack of energy drinks.