Turning Down the Volume

By Deirdre Longo

Several times during the past few years, I've mentioned during presentations that my first 10 years in information development seemed to be devoted to evangelizing information development and making space for our content. I, or my team, would make the case for being involved early, for building help into a product, for creating a consolidated information library. In each case, we were trying to get our information in.

My second 10 years have instead been focused around making the case to take content out. As a full-time, strategic information architect for a large and ever-expanding portfolio, I'm teaching writers to stop creating a help topic for every UI panel and focus on judiciously adding assistance only where users need it. Instead of writing about each and every product function, I'm advocating that they write about how users can achieve their goals and leave the edge cases to another day or to user communities or other developer sites. I ask development to remove Help buttons from the user interface.

As I read about information architecture and especially about content curation, I see the same focus on trying to control, corral, and simplify the incredible volume of technical content we've written in the past 40 years and that we continue to write. As an industry, we've built standard structures for developing information that result in a great deal of content. Customers already can't find the information that they need, in part because there's so much of it. What can we do?

The following are the basic tenets of my strategic architecture work with my product and writing teams—all aimed at enabling users to find and use only necessary content, exactly where and when they need it.

Discontinue the use of volume as a measure of productivity

This one is a killer. If the entire system is organized around measuring and rewarding volume, is it any surprise that we have so much content? Instead of measuring productivity, we need to measure value. Are we producing content that helps users successfully complete their work? In many cases, the content might not be written topics: it might be an installation program that detects what they have installed already and upgrades it for them; it might be a multimedia demo; it might be a change to a set of labels inside a few windows. I educate and encourage writers to be partners with development teams and usability professionals in the design of the product, showing how complicated parts of products will be to document and suggesting product changes that can reduce written content.

To measure value, we should conduct testing with users to see if they can complete a set of typical tasks. If we've been involved from the beginning in the development of the user interface, carefully selecting terms in the user interfaces and embedding assistance, users often won't need any additional information other than what they see in the product to complete their task. This is a much more valuable experience and a much better use of writers' time than writing help topics.

Educate teams to understand and apply models, not templates

We all want shortcuts and quick solutions, but our historical approach to building a library for a new product results in a huge amount of content. Teams without an IA (or limited access to an IA) tend to follow this historical approach—one help panel for each UI panel, one document for installation, one for administration, one for application developers, and one for users. The number of documents might change a bit depending on the product size and target audience, but this approach is a quick way to get to 1,000 or more topics in no time.

For teams I can't spend much time with, I ask them to answer the basic information architecture questions: Who are the users? What are their goals? What are the scenarios for users to achieve their goals? Where can we add content to help users and where will more content be less useful? If this is the first release of a new product, perhaps we should spend more time on overview material and installation and less on application development or customization. Each product is different and each set of users has unique needs, so building every new library from a cookie cutter will lead to too much of some information and too little of other information without the content ever being just right.

Prioritize high-value content and make sure everyone agrees to the priorities

High-value content addresses customers' needs. Again, we need to know who the users are, what they're doing, and how they will achieve their goals with our products.

Consider this continuum of possible content development efforts for a user interface panel:

Effort: Low (no investigation, little thinking, many words)
Value to customers: Little or none
Content: Describe how to work with the UI controls (for example, how to change a value in a spin control)

Effort: Medium (some investigation, little thinking, many words)
Value to customers: Some
Content: Field limitations, such as character limitations for the File Name

Effort: High (extensive investigation, thinking and negotiation, fewer words)
Value to customers: High
Content:

• Describe later consequences of choices, if any
• Describe any relevant interactions between chosen options; ensure programmatic assistance protects customers from making conflicting choices
• Make next steps obvious—for example, how to work with a downloaded file
• If there are choices or values to enter, programmatically recommend good choices or values and explain why
• Describe how to avoid or solve a problem, programmatically if possible

Customers know how to use user interfaces. Most customers know how to do most basic tasks in most operating systems. We don't need to spend time telling customers what they already know, but instead we need to spend time filling the gaps.

Gaps between tools and between products are particularly confusing. How do customers integrate two products? How do they enter data into one tool in a way that will make it readable by another tool? I like to tell writers that if they don't know the answer to a question, then a customer probably doesn't know it either. Their job is to be an investigative reporter and look for and report about what's hidden, not about what's obvious.

Carefully curate related content rather than just including it

Often writers are asked to include some content from another source with the rest of the documentation. Sometimes this content is for a related product, sometimes it's for a related use case, and sometimes it's related content with a different scope or perspective.

It's easy to just add the information. I encourage writers to do the harder but more valuable work of examining the content closely. Writers must ensure that it doesn't conflict with anything we already say, that it will blend well with our existing content, and that it will provide additional value. Often, the better solution is to include just a portion of the content or to build a map through the content, showing customers how they should make sense of the related material given the context of our product.

Because of our positions within our development teams, we are a trusted source for our customers. We need to continue to earn that trust by telling customers what they need to know, when they need to know it. Identify and organize the most valuable content for users, no matter where it comes from.

Trust your vision

We as IAs need to envision the design and sell that vision. Once we sell the vision, it's up to us to hold the space for our teams so that others don't start designing the information for us.

Because of that historical design perspective I described earlier, it's not just our writing teams who have expectations about what a library of information looks like. Our development and test organizations have the same expectations and so do our customers. We need to carefully review requests for design changes and see whether they come from valid requirements or from historical expectations.

When our team starts working with a new test team, we'll get defects that say, “There's not enough help” or “This panel doesn't have help.” When we ask what task they were trying to do that they couldn't complete, they usually respond that they could do their task just fine, they just thought there should be more help because there always is.

User feedback and testing are very much a part of our process and we need to incorporate changes into our design throughout the cycle. But we shouldn't be reactive with requests unless they reflect true information requirements.

There's some cognitive dissonance that comes with feeling like we're trying to undo what we built, but remember that this dismantling is a healthy sign! In any field, you must be willing to question all facts and rules. Any rule that becomes too rigid will mark the first step on the path to irrelevance.

Deirdre Longo is a strategic information architect for Enterprise Content Management products at IBM. She has over 20 years' experience in various technical communication roles: writer, project manager, technical editor, and IA. She is a co-author of Developing Quality Technical Information.