Last week, I was in the midst of a marketing sprint and decided to write a bunch of documentation for the SiteImp project. The current iteration is meant for significantly less technical users, so it wasn’t the typical documentation path. Instead, I got to really think about the product and the data it generates from a user’s perspective. Doing so gave me a much better sense of its overall user experience and helped me refine my entire mission for the product.

Writing documentation can seem like such a chore. And in all honesty, it should seem like a chore because it is. It’s hard work and is completely thankless. Well written user facing documentation rarely helps sell products, but poorly written docs can tank sales. Complicating matters, the difference between well written and poorly written is purely in the eyes of the beholder.

But complicating matters the most is the fact that you have to completely flip your perspective when you write user facing documentation. Instead of looking at it with the product person’s pride, you have to look at it from the perspective of a user who doesn’t understand. All the good has to disappear and you have to hunt the really confusing parts.

When you hunt confusing parts, you find them. When you find them, you can fix them. And when you fix them, you have to rewrite the documentation. Then, you have to hunt more confusing parts. Instead of using tests to drive the process, you use narrative. Unit tests verify if you have solved the problem correctly. Documentation can verify if you have solved the problem elegantly.

Then what happens when you can’t find anything else to write about?

Hopefully you have users because then you turn the second great burden (user support) into your next development philosphy. All of a sudden, those wonderful people who report problems aren’t reporting problems. They’re the best kind of testers - they’re people who are committed enough to your problem to pay you to fix it for them. And they found a problem (which is bad), but their bug report gives you the chance to do better in the future.

Ultimately, that’s why working with the web is so incredibly fulfilling. When you release things, you get to tap into every user’s creative potential. But as you release, take time and really think through your documentation. Ideally, you’ll be able to find the really confusing parts before anyone else does.

Strategies

This idea is incomplete so I know I’ll either discard it entirely or add to it. But I’ve come up with some strategies for writing effective documentation while simultaneously improving your product.

1 - Most b2b users would rather be doing anything else than reading your support materials

I’m going to be really honest. Lots of people hate their jobs. Most people would be happier if they didn’t have to go to work. But they go to work because they need the money.

When they’re reading your support materials, you’ve screwed them over twice. Not only are they are work, but their software doesn’t work the way they think it should. Instead of doing their jobs, they’re trying to figure out your shitty software.

Once you internalize that mindset, two things should naturally happen. First, you will feel grateful and apologetic because you hopefully are. And second, you’ll do your best to reduce the friction. Why make someone’s job suck more than it sucks by default?

2 - Onboard your users

A very small minority of your users will be passionate about your software. They will scare the shit out of you.

The rest only care in relation to whether it helps or hinders them at work.

If you write documentation with this mindset, you’ll be forced to think through the why of that feature. Why does it exist in the first place? Then as you write your support materials, you should onboard them with the why. Why are they here? What were they trying to accomplish? And how can you get them back onto that path?

You might discover that the path is badly overgrown and doesn’t make any sense. Or you may discover that you should just remove the feature because you don’t even understand why it exists.

3 - Orientate your users

When I write step by step articles, I like to write like this:

1. Click the settings button.
2. After you click the settings button, the settings screen will appear. You’ll notice that the gear icon has turned a darker grey. When you get to this page, click ‘user settings’.

I follow a pattern:

1. Follow this step.
2. This is where you are. This is how you know you are there. Now follow this step.

That does two things. First, it makes a little more sense to people who are really having a lot of trouble. But second, it forces you to consider whether your software has proper visual cues. Is it apparent that you’re on the settings page? Is it apparent which changes are potentially catastrophic? What kind of guide posts does your application have?

Final words

The idea isn’t fully developed and I’m sure that I’ll keep coming back with more content, but I hope that this changes how you look at documentation and providing support. Worst case scenario, I hope you’re even a little more compassionate towards people who need tech support. Some of them will become good friends and great beta testers!!

Good luck and happy building!