Approaching Help as Solutions to Problems — An Interesting Format from the CSS Cookbook

by Tom Johnson on Jul 1, 2008
categories: technical-writing

At Borders or Barnes & Noble, I often browse the computer books to see the different ways writers approach help material — especially how they approach the same help material.

The other day I wanted a book on CSS, so I pulled four available CSS books off the shelf and began browsing them. Each book looked respectable, but the CSS Cookbook, by Christopher Schmitt, had a unique format that caught my attention and convinced me to buy it.

In the CSS Cookbook, each topic is formatted with Problem and Solution subheadings. Here's an example: 

I like the problem-solution format. For one, while sitting there trying to choose the right CSS book, the problem-solution format convinced me that the book would deal with my actual problems, not just provide general CSS rules and principles. That feeling -- an extremely compelling one -- won me over to the help.

Almost invariably, the reason we turn to help is to solve a problem. Some would say every human action is driven by the desire to solve a problem (People don't go to Home Depot to buy a shovel; they go to dig a hole, as someone once said). But it's especially true for help material. Problems are the explicit motivation for why we turn to help. Consequently, help material that arranges itself around problems and solutions isn't too far-fetched of a format.

At the Trends Panel at the last STC Summit, the panelists even recommended that technical writers become problem solvers. Write less and think more, they said. You don't write -- you solve problems. As you solve problems, your value in the organization increases. They essentially recast our role from writer to problem-solver.

Perhaps it would change the way we wrote documentation if we looked at help as a collection of problems and solutions rather than features and functions. Rather than asking, What can a person do on this page of the application? instead ask, What problems might my user have here?

At the very least, thinking in terms of problems would perhaps get us out of the vocabulary of the application and into the vocabulary of the user. For example, rather than addressing how to "create navigation menus," we would be writing about building a "curved tab navigation menu that works even when text is resized" (as one problem in the CSS Cookbook is worded). The first is a general help topic; the second is phrased more after the language of users.

Some readers may object and say that we're already thinking of problems and solutions unconsciously when we write help. In part, sure. But adopting an explicit problem-solution paradigm would make us even more in tune with the actual problems users encounter. Rather than focusing on the general topics, it would help us focus on the scenarios where users will be challenged and confused.

The problem-solution format has its share of difficulties. The main difficulty is that some topics have problems, and others don't. A problem, in my mind, is one with specific circumstances and variables. A hairy situation. Here's an example where the problem-solution format feels forced.

 

In this example, the problem is so simple it doesn't feel like a true "problem." And the problem merely repeats the title, so it seems redundant. The repetition isn't needed, but for consistency's sake, the author carries the problem-solution format into every topic.

Another difficulty is crafting the topic title. At times the title succinctly states the problem; at other times the title strays from the problem. If the title just repeats the problem, the problem seems redundant. If the title is too different from the problem, the title seems poorly chosen.

In these situations, the saving grace is the Discussion section, which I haven't yet mentioned. After the Problem and Solution sections, the topic usually has a Discussion section that brings up other related points surrounding the problem. When a topic has a discussion that touches on several related issues or considerations, the repetition at the beginning is forgiveable. In that situation, the Problem section merely provides a concrete starting point for a larger discussion.

Overall, the problem-solution format probably works best for more advanced help, where the solutions are more complicated and involve combining several general principles or bending traditional rules. Despite the challenges I mentioned, in looking over the book, the format appeals to me more and more.