Characteristics of EPPO topics: specific limited purpose

This post is the second in my series on the characteristics of Every Page is Page One topics, an inquiry into the common characteristics of the millions of page-one topics that already exist. The first post in this series covered the standalone property. This post covers the closely-related property that an page-one topic has a specific limited purpose.

In the previous post, I introduced a distinction between a topic dependency and a reader dependency. A reader dependency is one the reader brings to the material — some wider purpose or some lack of background information or relevant data. A topic dependency is something the topic needs to fulfill its purpose for every reader. In order to tell a reader dependency from a topic dependency, you need to know what the purpose of the topic is.

It is natural for the author of a topic to have a specific limited purpose in mind when they write. When the author of a technical article like Bob DuCharme’s Push, Pull, Next sits down to write, they generally have a pretty good idea of what they want to write about and who they are writing for. That well defined purpose guides them as to what details are salient to their topic. Not every reader of the topic may instantly understand everything in it, but that is because they reader brings their dependencies to the topic, not because the topic is missing something in itself.

Similarly, when an author writes a recipe, they have a specific, limited purpose which they understand and which guides how they write the recipe. (The specific and limited purpose of a recipe is so well known that most recipes follow a well know template, something we will return to when we consider the tendency of page one topics to conform to a type.) Aspiring cooks may not understand everything in a recipe, because they have not satisfied all of their dependencies before attempting the dish, but that is not the fault of the recipe. It meets its specific and limited purpose.

However, in technical communication, it is often the case that manuals, chapters, and topics are not written with a specific and limited purpose. There is a common tendency for tech docs to grow and bloat over time as more and more material is included. But even in the first draft, many tech docs do not seem to be written to serve a specific and limited purpose. Why not? If it is so natural for the authors of millions of page-one topics on he web and in print to write to a specific limited purpose, why is it so hard for technical writers to do the same thing?

One reason is that the tech writer’s task is often defined simply as “provide documentation for the Widget.” As a purpose, this is neither specific nor limited. All too often, this vague and general purpose turns the topic writing task on its head. Rather than asking, what facts do I need to include in this topic in order that it fulfill its purpose, the author is left looking at a collection of facts to be included in the documentation, and asking. how do I create a set of topics or chapters such that all these facts will be included? None of the individual topics serve any purpose other than to be a container of facts to be documented.

A recent discussion on techwr-l illustrates the point. A writer asked what the correct form is for enumerating  multiple ways to do the same thing in an prodecure. Several opinions on that subject were offered, but the eventual conclusion of the discussion was that there was no reason to give more than one way for people to perform a step in a procedure. The purpose of the topic was to enable readers to do a specific operation with the product. One method suffices for that. Listing alternate methods is simply a distraction to the reader, presenting them with a decision they should not have to make.

This kind of thing appears all the time in technical documentation. There are even style guides to govern how it gets done. But it is outside the specific and limited purpose of a task topic. It is a case of having some extra facts left lying around after the user’s task was taken care of, and of a felt or mandated need to make sure those facts made it into the documentation somewhere. (If I were to buy a beer for every tech writer who has never heard a colleague, developer, or product manager say, “we have to tell them they can also use the keyboard shortcut”, I think I would have change left over from a six pack.)

Of course, most tech writers realize that fact-packing does not produce good documentation, and so they try very hard to figure out what their user’s needs are, and to meet them. This is certainly better than simply trying to find places to store facts. But it has snares of its own. In attempting to catalog the user needs that are to be met, it is easy to start including reader dependencies in the list of things a topic, chapter, or book must meet. When that happens, topics no longer serve a specific limited purpose. They become open-ended sinks into which every discovered defect of user knowledge and every possible branch of the user’s larger purpose is poured, until they cease to serve any reader well.

The answer is simple enough (though simple does not always mean easy).  We must refuse to put anything into a topic that is not required by the specific and limited purpose of the topic. If there are leftover facts that someone feels must be included, ask what purpose those facts serve, and write a new topic to serve that purpose. If there are user dependencies that must be met, by all means meet them, but not by including a user dependency in the current topic. Meet them by writing new topics with their own specific and limited purpose.

It is good enough for the rest of the world. It should be good enough for us.