One common criticism of technical content heard from users is that they are only getting information they already know—and they’re not particularly interested in consuming this “obvious” content. Unfortunately, in the name of rapid production, much content that is written describes the obvious about features, and doesn’t do justice to content that is truly valuable to those who want to consume it. Getting away from obvious content is at the heart of producing valuable technical content.
What do users find most valuable in technical content? To put it simply, users want to learn what they need to know – no more and no less. Users have questions in their heads, and they want type them into the search box, and get to a topic with a title that appears to answer the question. Better yet, after clicking the topic link and starting to read, users want to feel reassured that they are reading the information they truly need – and that it answers the question they asked. How often does this happen? Not nearly often enough.
I recently reviewed documentation for a product I did not know how to use (but I understood the domain), and found that most of the content failed to answer my questions about why certain tasks were necessary. As I was reading, I found myself asking “Why do I need to know this?” “What does this term really mean, and how does the corresponding concept impact my product use?” “Why did you use ‘4’ in this example? Is this the value I should use too? How do I decide what value I need to use?” “These results you are showing me, are they good? Why or why not?”
Three potential audiences exist for technical content – the User, the Content Developer, and the Software Engineer. In my experience, it’s the last two who are often the primary audiences for documentation, shortchanging the most important audience—the User. Content Developers, who usually know little about the software at the onset of a project, typically learn by writing. Software Engineers, who are typically frustrated by the learning curve of the Content Developer, tell him or her to simply write down truths that are self-evident, at least to the Engineers. This rather dysfunctional process results in a mix of basic material that isn’t likely to be needed, and advanced material that few or none are going to understand. But how do we repair this process and start creating technical content that truly has value for Users? Here are five tips for moving beyond the obvious to valuable.
1. Perform “Root Goal Analysis” before creating technical content.
At the onset of a project, a necessary conversation must take place between the Content Developer and the Subject Matter Expert (SME) about what the user will accomplish with the software. The Content Developer can ask the question, and, while listening to the answer, ask “Why does the user need to do this?” Many SMEs may not give a clear answer right away about what users are trying to get done. Asking “Why?” until the answer makes sense is essentially “root-goal analysis”, and similar to root-cause analysis. Getting to the root goal help ensure that both the topic title and the topic itself will address real users’ questions. If asking “Why?” doesn’t work, try asking “What wouldn’t the users’ be able to do if they didn’t have this feature?” Sometimes asking a question in the negative elicits the right answer.
2. Exercise the software with extreme mindfulness.
The Content Developer must practice extreme mindfulness while exercising the software to accomplish a user goal. What steps seem obvious? When did he or she have to make a decision? What stumbling blocks did the Content Developer encounter?
Exercising the software with a well-honed taste for the clunky and the difficult is critical in identifying necessary – and valuable – technical content. After discovering the knots in software usability, the Content Developer should discuss them with the SME to identify what is truly difficult, versus what is part of the Content Developer’s learning curve. Content Developers should trust their instincts and be wary of SMEs who say that something is easy. Sometimes SMEs are right and the concept or task is easy. But Users are busy people and prefer that the software and the documentation speak clearly and simply, and not tease their brains. The Content Developer’s craft demands the ability to discriminate between the obvious and the challenging while iterating on the technical content with the SME.
3. Ask the SME as many questions as needed to distinguish obvious from valuable.
The gift for asking questions is a trademark of the established Content Developer. “What is this?” “Why would the users want to do this?” “What happens when I do that?” “Why wouldn’t the user want to do that (since you are making it easy for them to do it here)?” “What does the user get?” “Are the results any good? Why or why not?” “What happens if the users set this incorrectly?” “What can go wrong here?” Content Developers should look at the error messages to assess the potential pitfalls for the user. The Content Developer must get to the “skinny” of the matter by coming at it from all directions, weighing each SME answers with his or her gut. What’s obvious, and what’s valuable?
4. Prioritize creation of decision-making, task-based, and troubleshooting technical content.
When users start using the software, they typically need to either decide what to do first, or do something, or fix something that isn’t working. This is the content they need most. Thus, Content Developers should prioritize writing decision-making, task-based, and troubleshooting information before writing conceptual topics.
Conceptual topics must support a task or a decision in the software. Otherwise, such topics are useless. Textbooks often include conceptual topics, but who loves textbooks? If you are like me, you may have found many textbooks cryptic and impractical. Textbooks are the opposite of useful technical documentation. I often use the “Delete-Key Test” to determine if content is useful: “If I were to delete it right now, would anyone miss it? Why or why not?” If I know why someone is going to miss content that I pretend to delete, I can rewrite it in a way that makes the connections valuable.
5. Peer-test technical content.
Peers, in the absence of true users, are the most valuable resources for testing whether and how technical content complements software usage. Content Developers can pose a realistic task for their peers, with the help of the SME, and watch their peers perform the task with the help of the documentation. While peers maybe not be able to comment on technical accuracy of conceptual explanations, they can certainly help flag what’s clear, missing, or obvious.
When Content Developers accept that everyone has a tendency to initially write the obvious, they can aggressively pursue the valuable technical content. Establish user goals and write toward them, including only in the information that bridges the gap between the known and the unknown.
