By Alyssa Fox | Senior Member
For many years, technical communicators provided content in the same way—comprehensive books that described everything one could possibly want to know about the product or tool they were documenting. My organization was no different. We wrote many books that described our products and (we thought) described them well. As time went on, however, this approach resulted in large, unwieldy documentation libraries that users couldn’t really use because the documentation was cluttered and didn’t provide the right kind of information they needed.
After some thought—and many customer complaints—we started planning a new model for the kind of content we wanted to give users. We recognized that instead of going with the whole-hog approach, we needed to provide the right content at the right time to the right people. Though this type of content required more research, knowledge of our users and their goals, and more time to write, we knew it was the direction we needed to go.
In heading down this path, not only did we plan to improve the quality of the content we provided to our users, we expected as a team to provide more value to our organization as we expanded our skillset to include more thorough task analysis, persona definition, usability testing, and video creation.
We had several goals we wanted to accomplish by revamping the way we presented content to our customers:
- Provide a positive user experience with our products. To do that, we knew we had to offer sufficient information for our customers to use our products effectively.
- Provide high-quality content based on understanding our users and their content and format needs.
- Improve product user interfaces so that they are as simple to use as possible, are easy to figure out, and require less explanation.
Implementing such a large change to the way we wrote and delivered content required some change management and evangelization. The entire information development team spent a lot of time meeting with other stakeholders in development, product management, and technical support to describe what we were doing and the anticipated benefits of this new model.
The benefits that we anticipated as a result of this new content model are:
- Clearer content
- Easier reuse
- More effective use of team members’ time
- Reduced costs for maintenance and translation
- Improved quality
- Fewer technical support calls
- Better user experience
- Happier audience
User Documentation
Through the past few years, we started receiving many comments from customers that our documentation showed them how to do things, but not when to do them or why. So we started rethinking the way we wrote that documentation. If our customers couldn’t achieve their job goals with our documentation, something had to change.
Traditional Documentation
In order to understand how targeted documentation is valuable, it’s important to understand what traditional documentation is and the differences between the two. My organization had been doing traditional documentation for many years. Traditional documentation tends to document features in a product and show users what they can do with the product.
Traditional documentation values comprehensiveness, which can lead to the “everything and the kitchen sink” approach. This approach documents every possible thing one could know about the product, yet doesn’t provide information on how those features help the user solve their pain points.
Traditional documentation values consistency. If you create context-sensitive help for one wizard, it’s expected that you create context-sensitive help for all wizards. This level of consistency doesn’t take into account the fact that some wizards might be self-explanatory and not need additional documentation.
Traditional documentation also tends to step users through everything in the user interface, regardless of how intuitive that menu option or window might be. Additionally, this kind of documentation sometimes tries to compensate for bad interface design. If usability is poor in a particular area of the product, often the project team wants the documentation to address it, rather than fixing the issue in the product.
Focusing on comprehensiveness, consistency, and the user interface results in traditional documentation aiming at the least-skilled users. In today’s businesses, more IT team members are handling multiple areas that they didn’t before, so they need advanced guidance, examples, and scenarios to help them manage their complex environments.
Targeted Documentation
Targeted documentation requires a solid knowledge of users, their needs, and use cases. This type of documentation takes more time to research and write, but is more valuable and provides a better user experience when they can see how our products help them do their jobs. Following a concept-procedure-reference model when writing targeted documentation helps the users learn context before following a procedure, and separates reference material from main text, reducing clutter.
Targeted documentation provides specific information when and where necessary, rather than generic information about every aspect of the product. Big-picture tasks, workflows, and best practices information help guide users in making decisions about what they are doing and why. The focus should be on the user, not on the product.
Extensive and relevant examples, scenarios, and troubleshooting information all provide user assistance in a way that helps them connect the product’s functionality to the goal they are trying to achieve. If they can see an example that is similar to their situation, it is easier for them to understand how to use the product to work in their environment.
Finally, targeted documentation does not document the obvious or the easily discoverable. It costs money and clutters documentation to write about things that are intuitive in the user interface. If you are having difficulty determining what is easily discoverable, run some usability tests on various tasks and see what results you get.
Writing Style and Content Format
Though targeted content differs from traditional content, some tools remain the same. For example, having a style guide and considering how to write for localization are important in ensuring the content still looks like it came from one organization, despite multiple writers having worked on it. Templates for your user documentation and videos help ensure that level of consistency as well.
Consider which content formats make the most sense in various situations to ensure you are providing information to users in a logical way. Sometimes context-sensitive help is the appropriate delivery mechanism for content, sometimes putting text in the user interface directly is the right answer, and some information makes the most sense in a PDF guide.
Content Design
Keep in mind that targeted content does not always mean less content. It means providing the appropriate amount of content to help users solve their problems. In certain cases, you might find that you need to provide more information to make your users successful. In my organization, an enterprise software company, we found that many of our customers wanted more comprehensive installation and configuration information. They were having difficulty determining where to install which components of our products and asked for examples and scenarios to help them make those decisions. They also requested additional troubleshooting information so they could attempt to figure out issues they were having on their own before having to call technical support.
Users had fewer problems with other types of information like product usage, conceptual information, and reference information. To determine what specific information we needed to provide in those areas, we did thorough task analyses to see what their top tasks were, determined how obvious or self-discoverable the user interface was around those tasks, and wherever we could fixed the user interface first before documenting anything.
Best Practices for Targeted Content
When you are ready to start with targeted content, there are some important principles to remember. Start with the minimum information a user needs to perform a task. As the writer for a product, you will know more than the user does about the product. However, refrain from adding information that may be informative but doesn’t directly relate to completing that task.
When discussing or demonstrating tasks in a user guide or video, ensure you include information about why you would use a feature to perform a task with the software, and relate that information back to your users’ goals. Use graphics, screenshots, and demos where they are relevant and useful. Often a graphic can describe a concept or workflow in a much better way than text can.
Assume the user has knowledge appropriate for their jobs. In traditional documentation, writers often described everything about the product, including basic information. Targeted content aims to let the user interface speak for itself and provides information for users at their level of knowledge.
Finally, get out of “book mode.” In the targeted content model, consider the best format for your targeted content. Those formats might include video, context-sensitive help, books, text in a user interface, or tool tips.
User Experience
The main goal of targeted content is to improve the overall user experience. Our users want easier-to-use products, not more user documentation in book form to make up for user interface problems. Therefore, part of working with targeted content is evaluating the overall usability of a product and its associated documentation and seeing where we can improve.
One of the ways we decided to help improve the user experience was to begin doing usability testing on various tasks users need to perform with our products. We follow the method described in Steve Krug’s book, Rocket Surgery Made Easy. This method of usability testing is inexpensive and can be done quickly, and still gives you great results on how you can improve the product so you don’t have to document around usability issues.
The writers also assist developers with user interface text and screen flow. Working in an agile environment encourages the team to work more closely together each day and communicate more to streamline activities like this throughout a sprint, rather than having to go back and change interface strings after they have been coded. The writers also assist in writing error messages. Any time you can keep users from making a mistake—or guide them in what to do next if they do make a mistake—their user experience is improved.
Entering usability bugs and pushing back on the project teams when they try to fix user interface problems with documentation also help guide the development team to thinking more about usability. As we work through these issues with the developers, we are constantly thinking about how to improve the user interface so that less documentation is required and how we can design new user interfaces or help systems so that every window does not require a help topic.
Converting to a Targeted Content Model
Prior to actually making the switch from traditional documentation to targeted content, it’s a good idea to evangelize the new model to all of the stakeholders in your company so they understand the upcoming change. The fact that it is a significant change means you will have varied reactions from your project teams, so be prepared for that. Ensure that you can support your decisions to those people who don’t understand what you’re doing and why. Gaining buy-in from your user advocates, such as product managers or professional services teams, will help you in your attempts to convince others of the benefits of this model. Recognize that this change will not happen overnight, and continue to communicate and over-communicate the plan and its anticipated benefits.
Converting to a targeted content model includes several steps. The steps my team uses are as follows:
- Define your users. Knowing who your users are and their pain points are essential to targeting content toward those users. Continually clarify user descriptions, personas, and use cases. Keep in mind that you are not your user. There are several ways you can gather information about users:
- User definition meetings with user advocates (product managers, technical support, professional services, and sales engineers)
- Customer forums
- Technical support sessions
- Sprint demos
- User conferences
- User comments on online documentation
- Conduct a task analysis to define the top tasks that your users perform at their jobs. Think about what problems your product or solution will solve for those users and the core tasks the user wants to accomplish. Ask yourself the following questions:
- What are the essential tasks the users must do? These tasks are the ones you want to focus on when targeting your content.
- What are the important but nonessential tasks? These tasks are not top priority for documenting.
- What top user goals can you base your core tasks on? These goals should not be based on product features.
- What tasks are discoverable by the user? Don’t document these tasks at all.
- Build your targeted content plan. Ensure your plan includes the following considerations:
- Do not build the plan based on current content structure. Start from scratch to think about what information the users really need.
- Address the main areas for which your users have requested more information. Additionally, determine the best format for various pieces of content, such as video, user interface text, or user guide.
- Work usability testing into your plan. The easier the product is to use, the less content you have to write or demonstrate in a video.
- Determine what existing source material fits into your new plan, what needs to be rewritten, and what outdated or obvious information you can remove.
- Review and refine the plan, using the following steps:
- Review your plan with your manager to gather feedback on content organization and deliverable formats.
- Review your plan with project stakeholders to ensure the plan addresses top user needs and to gain buy-in for the change coming up.
- Incorporate feedback into the plan.
- Create a schedule for incrementally building targeted content into existing documentation sets over multiple releases, adding additional types of content where necessary.
Higher Value and Happier Users
Throughout the exercise of defining, evangelizing, and implementing the idea of targeted content in my organization, it has been widely recognized that our information development team provides more value to our users and our organization with this model. We have successfully migrated from the traditional approach to the targeted approach for the content for several of our products and have seen customer satisfaction rise with the new content we are providing them.
Usability testing has been a huge eye-opener to our development teams and really spurred them to make significant usability changes in our products as a result of those tests. We continue to offer those as an option, and most of our teams want us to do more of these tests than our workloads allow. Therefore, we are now teaching others in the company how to moderate those usability tests, raising our team profile. It is now widely known throughout our organization that we do more than “write books,” and we are contributing significantly to increasing the quality and usability of our products.
Delivering our targeted content in multiple formats by adding videos to our deliverable formats is getting a lot of buzz too. Our users have been asking for videos for a while to show them how to perform the more complex tasks they must do each day in their jobs, and we are happy to be able to start delivering those. Having videos and interactive software simulations as part of our targeted content plans shows the rest of the organization that we can learn new tools and expand into new offerings, thus increasing our team members’ value in the organization while also addressing user requests.
Finally, the targeted content model pleases our users—and that’s our top goal. It’s easier for them to use our products when they are intuitive and usable. It’s easier for them to use our products when they understand why they should do something with the product to help them solve their problem. It’s easier for them to use our products when the documentation is not so full of extraneous information they can’t find the bits they actually do need. And it’s easier for them to use our products when they have examples and scenarios that are relevant and similar to their situations. Delighting our customers in this way makes it easier for them to do business with us, and that’s the most important thing.
Alyssa Fox is director of information development and program management at NetIQ Corporation in Houston, TX. She is a member of Customer Experience Professionals Association (CXPA) and User Experience Professionals Association (UXPA). She is also a senior member of STC and is currently serving as the STC Secretary. Alyssa speaks at numerous international conferences about various management, agile, and technical communication topics. Find Alyssa on Twitter @afox98.
References
Aschwanden, Bernard. Minimalist Writing Online Course, www.stc.org/education/online-education/certificate-courses/item/minimalist-writing.
Hackos, JoAnn. Managing Your Documentation Projects. Hoboken, NJ: Wiley, 1994.
Krug, Steve. Rocket Surgery Made Easy. Berkeley, CA: New Riders, 2009.
