Search results

Turning Around the Disdain for Help by Focusing on Content

by Tom Johnson on Jul 18, 2013
categories: technical-writing

For a long time I pursued findability as a solution to fixing the documentation problem. But lately I've been less persuaded that findability will solve documentation's ills. Instead, I'm become convinced that what's really wrong with help is the content itself, not necessarily allowing people to find it. Why? Because "it" often doesn't exist. The user is trying to find something that hasn't been created.

What's really wrong

First, a quick recap. Although many advancements in tech comm have enabled us to be more efficient -- such as single sourcing our content across multiple channels, fitting content into well-defined structures, producing good looking HTML, PDF, and mobile outputs without requiring programming knowledge of interaction design skills -- many users still get frustrated with help. They still view it with disdain. (See my post Do We Need a New Approach to Help? Why Are Users So Apathetic Towards Help after 50 Years of Innovation?" for more details.)

The feedback I receive about help content (as with my blog) rarely relates to the design of the help, or the grammar. Instead, the problem is that the help doesn't contain the answers to address the user's questions. In other words, the problem with help content is the content itself.

Why help content suffers

One reason help content suffers is because technical writers are often more interested in the bells and whistles around content instead of content itself. We may be focused on tweaking a design, getting the CSS styles just right, figuring out the page layout setup for the single sourcing situation, or gathering requirements for a new tool. Some writers are excessively attentive to trivial details, like an exacting obedience to arcane comma rules or noting em versus en dashes.

Don't get me wrong. These are important tasks, but sometimes I think tech writers tend to avoid writing content, because we find content boring. It's much more interesting to be involved in usability, or information architecture, project management, business analysis, XML, content strategy, or some other ancillary task outside of help content creation. Indeed, sometimes content creation has been relegated as a lower-level skill, on par with "typing." No wonder we often avoid focusing on it.

As a result, help content tends to be neglected. Users don't find answers because the content itself is poor. So they consider help useless, and tech writers suddenly find themselves trying to defend value propositions about their profession, and so on. It's a downward spiral once the content is rotten.

The next time you attend a professional technical writing conference, look at the list of sessions that actually address content creation. Many conference speakers don't engage in content creation themselves. They are vendors, or consultants, or managers, or specialists -- and the topics are often about the platform, publishing process, or output. Content takes a backseat.

The irony is that the efficiencies of help tools today allow the technical writer to focus on content more than ever before. The platform in many cases is easy to set up. You can choose from dozens of tools that make the authoring process simple and painless -- so you can focus on what really matters: the content. Still, even with all barriers cleared from our path, the road to content is usually not taken.

Fixing the help content problem starts with focusing on the content

To fix the problem of poor help content, we have to start shifting our focus to the content itself. Fortunately, focusing on the content (rather than a more efficient workflow to deliver content) is where tech comm careers -- at least in my experience -- start to get interesting. That's the paradox. The content seems so boring ... until you start swimming in it. Then all the complexities, depth, varieties, and other facets start manifesting themselves, and suddenly everything else dims in importance.

Here are a few ways to start giving priority to content:

Drive content creation based on user feedback. Hook into your support tickets and see where users are getting stuck. Write content that addresses users' questions and helps them achieve their goals. In short, start listening to user feedback from support groups. They're usually talking about your content, and there's almost no better way to align your focus correctly on content than to start focusing on the user.

Focus on content post-release, not just pre-release. Content isn't finished once you push out an update. Once you release an update, that's when you should start really listening for user feedback. Post-release is when the real questions start pouring in. Never consider help complete -- it is always evolving, especially when first published. Your release week is like the trilobite stage of help.

Stop limiting help to obvious material that satisfies mainstream use only. Given the trend with improved user interfaces and increased user technical abilities, help that states the obvious will often be useless. Provide the difficult information not immediately apparent. Even if only a handful of techies benefit from the advanced information, they can disseminate the information widely to the masses in forums and other channels.

Stop communicating in ways that don't connect with the user. Instead of producing big walls of text, flex your rhetorical muscles and create content that engages users. Get visual with concept diagrams, illustrated screenshots, videos. Get concrete with code samples, common scenarios, process workflows, and more. Break out of the simple list of steps, which rarely satisfy the hungry user.

Test code yourself. Whatever you're working with, test it yourself. Try it out. Rarely take someone's word for it. Although you may not always have access to test something, or bandwidth, it's a best practice to make sure something works as advertised. When you test things out yourself, you often find more details, stumble on new questions, and create much better content.

Become immersed in the business knowledge of your industry. The saddest fact of tech writing is being an outsider who is writing content for insiders. The more you use the product, the more aware you become of questions, scenarios, and problems real users will encounter. Understanding the business context of the product is critical. The business knowledge infuses your content with context and meaning.

These strategies aren't revolutionary, but implementing them can change the whole dynamics of a technical writer's work. Each of them will encourage you to focus on the content itself. And that focus on content, more than anything else, will go a long way toward changing user attitudes about help.

But what about career marketability?

There are still a lot more questions to address when adopting a content-heavy focus. When you focus on content, what about your career marketability? Strategically, tech writers usually specialize in something in addition to technical writing to ensure career marketability. I've heard the advice countless times: You want to make your career title a hybrid, to be a technical writer and an information architect, or something. That's because technical writing itself is seen as a commodity, a task so low-level that it can be outsourced to another country or perhaps to an intern. Tech writing isn't a solid enough skill to stand on its own. Doesn't my advice about focusing on content, then, encourage career suicide?

I hope not. More than anything, focusing on content will convert you from an observer to a subject matter expert. And developing subject matter expertise in an industry is often more valuable than any tech comm skill, such as knowing how to set up templates in an authoring tool (which one company might use but not the next).

Subject matter expertise in an industry often marries you to that industry, but not always. For example, I'm getting more technical. The documentation I'm writing is more geared towards developers, and creating developer-oriented content means I'm learning programming languages, especially in the context of SDKs and APIs. That subject matter expertise won't necessarily lock me into a specific industry (like medical expertise might encourage a career in pharmaceuticals), but it does keep me close to IT departments.

A limited discussion?

I'm also aware that focusing on content may cut me off from the larger, overarching tech comm discussions. If I suddenly start writing about engagement strategies and JavaScript techniques, how will those topics connect with other tech writers focusing on storage arrays or netbeans or whatever? What will be the common language and topics for discussion around content that doesn't involve the details of the content itself?

That question I'm not sure about, but I know that fixing content starts with a focus on content. I'll be interested to see where this focus leads.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.