Tips and Tricks: Getting from Obvious to Valuable Technical Content

valuable technical contentOne 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.

Mark Baker

5 years ago


I think you hit the nail on the head with the questions you pose:

“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?”

What is important about these questions is that none of them are mechanical. They are all decision support questions. This is where I think tech comm has really dropped the ball on task oriented documentation. We need to understand that the part of the task that the user usually has trouble with is not the mechanics of how to press the buttons, but with the decisions they have to make in order to know what order to press the buttons in.

Of course, providing decisions support is much more complex than telling people how to press buttons. You can’t get at the decision support information by sitting in your cubicle playing with the beta software.

But what users generally want and need is decision support content, not help on pushing buttons.


5 years ago

Thank you for your comment.
Yes – task-based documentation implies “task- and decision-based. I agree that this part of technical communications is not mechanical and is therefore more challenging to write. However, decision-based information is probably the most important information we can provide such that the user can extrapolate future actions.

The Real Docs Need is Decision Support - Every Page is Page One

5 years ago

[…] her recent article on TechWhirl, Tips and Tricks: Getting from Obvious to Valuable Technical Content, Ena Arel talks about the kinds of questions she finds herself asking when reading documentation: […]

Jonatan Lundin

5 years ago

I find your tips to be really valuable. What you’re talking about is really the ingredients of a design methodology. Technical communicators tend to focus too much on single tasks and not the reasons to why users want to do tasks. A design methodology must help technical communicators move beyond just simply listing tasks as the fundamental process when designing manuals. For the last five years or more, I’ve been advocating a new methodology called SeSAM to design and plan technical documentation where focus is to predict the questions users ask when using a product.

First of all, why do companies develop technical products (hardware, software etc)? Frankly put, since they have recognized that people on certain markets have needs to solve problems, requirements or desires. Why do anyone buy and use a technical product? Because people have a need to solve problem, requirements or desires. They (users) are willing to use it since they have understood that a product can help them solve a problem, requirement or need (=a primary goal). Technical products are designed to be used to deliver an outcome that solves a need. Users use the product to make it deliver the outcome that solves the need. Users are not doing tasks without a goal in mind; no user is doing tasks just because it is fun to do them.

At certain usage situation, users ask questions during the process of using the product to solve a problem or requirement. They end up in a search situation, which is due to the “least effort approach”, active and goal oriented behavior (minimalism etc). Users want the answer quickly and without putting in a lot of effort. So what questions do users ask? And how do we get to know them before they are asked (as in a predictive, pre-release approach to documentation)?

According to SeSAM you need to model the primary goal(s) a product is designed to solve, similar to the “root goal analysis” you are depicting. Then you must model the secondary goals the user must perform to make the product solve the primary goals. For each secondary goal(s) for each primary goal, it is possible to derive one or many sub goals, called a task situation (equal to a use case, user story or scenario). SMEs are a great help when modeling these goals.

Task analysis (using for example hierarchical task analysis) is done to model the steps that the manufacturer recommends the user to follow to reach a sub goal. To perform each step, the user must possess procedural and conceptual knowledge. The information architect must identify the steps, meaning the procedural and conceptual knowledge, that the user community is assumed to know, which means that a lot of steps can be “removed” from the task analysis tree. Usability tests are one way of identifying what users already know or can figure out from the UI. The remaining procedural and conceptual knowledge that the user community is assumed to not know, is transformed into user questions.

You end up with a number of questions which are classified according to the SeSAM facet taxonomies. The SeSAM facet taxonomies are populated as you analyze and identify the primary goals, secondary goals etc. To allow a user to find an answer a rich search user interface must be designed, for example as a faceted browsing environment. The SeSAM approach means that you are not organizing content in static arbitrary hierarchies (table of contents).

As a technical communicator, you move from managing user manuals to manage user questions and their classification.


5 years ago

This is an interesting idea:
“…you move from managing user manuals to manage user questions and their classification…” It reminds me a little of what the Tech Support world is trying to achieve. Except, in your case, these are questions that Content Developers anticipate users will ask (at least before the features are released) AND the questions users actually ask after getting the features. Sounds like there may be an opportunity for a tighter integration between Content Developers and Tech Support specialists.

Jonatan Lundin

5 years ago

Yes! To integrate tech com and support is something that I’m sure will happen more and more in future. I recently suggested to the DITA community (and TC) to integrate content management support for tech support content into DITA (see a discussion here

Technical communicators are predicting user questions (or should be doing it) since we often work in a pre-release mode. And or focus should be to design rich search user interfaces (SUI) that allow a user to find the answer quickly. So our focus should be to 1) predict questions and craft the answers and 2) design a SUI that enables a user to find an answer. To be able to predict user questions, we must understand the information-seeking behaviors of users. Something I have elaborated on here:

The tools (editors/viewers etc) we use today constrain us to some degree since they do in many cases only provide a mechanism to create table of contents or indexes. We need something else. Or our users do.