The Vocabulary of Tasks

By | 2011/05/15

Task orientation is one of the most important principles of technical communication. But it is also a more difficult concept than it might at first seem. Part of the problem is the vocabulary of tasks.

When we urge writers to be task oriented, we usually contrast it to a different style, which we often call “feature oriented”, or “product oriented”. We say things like, “write about the task, not the product”, or “stop talking about the product and start working for the user”. All of this can make it sound like it is a bad thing to even mention the product and its features. This can lead writers to try hard to avoid framing any task in product terms. Consider this progression of titles:

The breakpoint dialog box

A classic feature oriented title. No hint of a task here.

Using the breakpoint dialog box

A cosmetic attempt to make the content sound task oriented. Chances are nothing has changed but the gerund in the title.

Setting breakpoints

Okay, now we’re getting more task oriented. This is focusing on the user’s task. But, it still mentions the product feature. Hmmm…

Stopping the execution of your code

There, now we’re really task focused. No hint of the product in that one. It’s all about the user.

But wait a minute. If I’m a programmer, and I want to know how to set a breakpoint in your product, what am I going to type into the search box in the help, or look for in the index or TOC? “Stopping”? “Execution”? “Code?” No. I’m going to search for “breakpoint”.

The point is, task orientataion is not about avoiding the use of the names of product features at all costs. It is about helping users do their tasks. And since they bought your product to help them do their tasks, chances are, your product’s features are going to come up at some point.

In order to support the user doing their tasks, we have to use the vocabulary that they would use to describe those tasks. In doing this, we cannot assume that all users are complete novices who have not only never used your product before, but have never done the task before at all. The vocabulary that users use to describe their tasks actually comes from three sources:

Goal vocabulary: Some users express their tasks in terms of the goal that they want to achieve. These users are closest to the idealized novice that many tech writers assume they are wiring for. They don’t have any technical vocabulary, so they can only express their task in terms of their goals. But more experienced readers may also express some of their tasks in goal terms.

Craft vocabulary: Some users express their tasks in terms of the standard vocabulary of a trade. Programmers use terms like “breakpoint” and “linker” and “merge”. Technical writers use terms like “proofread” and “em-dash” and “metadata”. If you are writing about how to do the common tasks of a craft using your product, you should use the vocabulary of the craft (even if it happens to overlap the terms used in your product interface).

Tool vocabulary: Some users express their tasks in terms of the features of particular tools and products. Technical writers might talk about FrameMaker’s “Markers” or Word’s “Document Map” or oXygen’s “Grid view”. Long time users of your product are used to your product’s terminology and to avoid using it is simply to hide information from them.

Of course, not every user comes to your documentation with the same vocabulary. But to write as if every user had just fallen off a turnip truck, and had no knowledge of the vocabulary of their craft or of your product, would be to do them a great disservice. Task orientation is not about avoiding any mention of the product; it is about helping readers get their work done. The terms they use are the terms you should use. Even if those terms happen to include the names of your products features.

But no, this is not a licence to go back to descriptions of “The Breakpoint Dialog Box”. It is about giving readers the information they need to set breakpoints. But if that means letting the works “Breakpoint Dialog Box” slip out, that’s okay.


4 thoughts on “The Vocabulary of Tasks

  1. kevinmcl

    In your first paragraph, you said “Part of the problem is the vocabulary of tasks”.


    It gets especially tricky when your product is powerful and flexible and is being sold to address tasks in wildly different markets. The same base task, from the perspective of the product, might have different names and associated vocabulary for the person needing to perform that basic task in an inter-bank clearing house, versus the person needing to do something that incorporates the same basic task, but for US Homeland Security or Israeli MOSAD.

    One thing that alleviates _some_ of that problem is that companies building such products often sell to their end customers through middle-layer VARs (value-added re-sellers) who often amalgamate and massage documentation from several source companies into the final “product” or service that they sell to the bankers or to the government spy agencies (or the petroleum industry, or the publishing industry, or the utility companies … or…)

    Indeed, it might be those value-added re-sellers who take on the task of getting translations done.

    Pity them.

    1. Mark Baker Post author

      Thanks for the comment.
      Certainly the OEM/VAR relationship makes the question of task definition and task vocabulary more difficult.

  2. Joe Pairman

    Great article. I totally agree. We shouldn’t feel we need to expunge all feature names or technical terms. Sometimes the awkward avoidance of such terms results in a topic that’s harder to read. And in fact it’s not only experienced users who use these terms to search. For example, in consumer electronics, many people of all levels of experience search for information on popular new features and technologies.

    Still, where there are multiple common terms, we don’t have to cram them all into the title. They’re also quite valuable if mentioned in the first sentence or two. And meta keywords are another good place to put key terms, provided that the internal search tools are configured to include them. (Of course, these keywords aren’t searchable from, though other Google products and other search engines can include them.) For those using the DITA-OT, a nice feature is that it uses index terms as the meta keywords in HTML output, so you don’t have to create a separate index for PDF.

    1. Mark Baker Post author

      Hi Joe, thanks for the comment. I agree, these are all good places to capture alternate terminology, so far as we are aware of it. One of the nice things about Google is that it can link our content to alternate terminology even when we are not aware of it. Re using index terms as meta keywords, the SPFE-OT does the same thing (or rather, will do once it is made public).


Leave a Reply