Daniel Compton

Several years ago fresh out of University, I needed to update some software at the company I was working at. The update required the users to make a change to their local machines configuration. I knew this would be a bit tricky for some of the users so I sent an email with an explanation and instructions. However instead of including the instructions in the email, I just gave a link to the manufacturers documentation. I thought about copying the five lines of instructions into the email but didn’t. I reasoned that “Of course they can just click the link and read it. There’s nothing hard about that”. In my naive idealised world full of people who enjoyed reading documentation, this would have been fine. In the real world, the change didn’t go very well.

After sending the email, many users didn’t click the link to the instructions and didn’t make any changes. This caused confusion and frustration for them and me over the next few days. After thinking about this on the weekend I knew I had to resend the email. I resent the explanation email but included the documentation inline and added an explanatory picture. This time, everyone picked up quickly what they needed to change and the switch went easily.

Including a link to manufacturer documentation seemed perfectly fine in theory. However it would have been better to let go of my expectations of the users and give them what they needed, rather than what I thought they should want. Often as technologists we have a tendency to build our software for how we want our users to be, not how they are. In certain cases that can work, but most of the time it is better to meet our users where they are.