Spark Content

As writers, we’re flexible when it comes to how we get the information that we need for a project. We’re just as comfortable talking to someone, going through the software ourselves to pull out information, or reading through reference documentation and turning it into user-facing documentation – usually we do a bit of all three! While it’s great to have developer requirements or marketing materials as a starting point, we can’t just edit them and call it a day. As handy as they can be, they often fall short of what we – and users – really need.

It’s all about perspective

The best documentation addresses what users are trying to learn, not what the writer is trying to tell them to learn. Many developer and marketing documents tend to focus on what the writer wants the reader to know. We can’t fault them: people tend to write about what they know. Developers know how they’ve coded the user interface, so development documents tend to outline the UI elements and their options. Marketing teams want their product to sound better than the competitor, so their documents list flashy features and impressive statistics. But, both often miss out on why the user interacts with the documentation. Users don’t want to know what settings are on a screen. They want to know why they need to use those settings. And that list of flashy features loses its shine if users don’t know why those features are so great. When thinking about user documentation, it’s important to understand the user’s goal in reading the documentation.

The key is thinking about why, not just what or how

To get to the user’s goal, we ask questions. The first two are “What does this do?” and “How do you use it?” While it might seem like that’s all the information that you need, it’s missing one important piece. The what and how don’t help users without also asking the why.

If I told you how to change your phone settings so that applications closed after a set period of inactivity, what would be your incentive to use this feature? It might take you longer to open the app the next time you wanted to use it. That doesn’t sound like a useful feature and you have no reason to use it. But, what if I told you that closing your apps made your phone battery to last longer? There’s your incentive. There’s the why.

By asking questions, we find the why that users are looking for. We also sometimes uncover awkward workflows that come from forgetting the why. For example, you might have two teams who are working on two separate, but related, features, each with its own settings screen. If you focus only on the how of changing the settings for each feature, it might not be obvious if users must make changes on one screen before making changes the other. If the task done frequently, switching back and forth between the screens isn’t the best solution. Asking why a user is changing the settings reveals that it is more effective to have the settings on one screen, regardless of which team coded the features.

Writing is about anticipating what users want to know

It’s easier to write about what a product or feature does. But, it’s more effective to write about why someone would use the documentation for that product or feature. By focusing on why, you are more likely to meet their needs. And, if you can’t meet their needs, they’ll go somewhere else that can.

If you aren’t sure if your documentation is giving users what they need, the writers at Spark can help you find the right focus.