In The Tyranny of the Terrible Troika, I complained that the now almost universal trio of concept, task, and reference did not properly represent what topic-based writing and information typing are really about, and I promised to show why each one, as popularly practiced, fails as both a topic type and as an information type. I begin with this: a task is not a procedure.
The most commonly used “task topic” type today is that implemented by DITA, in which a task topic is essentially a procedure. A procedure is certainly, in the Information Mapping sense, an information block. It is a distinct literary form, with a defined set of rules and a clear beginning and end. You can certainly create and structure procedures as discrete blocks of content. But they are not task topics.
The distinction should be very clear. A task is something a user has to do, a goal they want to attain. A procedure is a set of instructions for manipulating a machine. Manipulating the machine is never the user’s goal in itself. Manipulating the machine may be one of the things the user has to do to accomplish their task, but it is not the task itself. A procedure, therefore, may be part of a task topic, but it is not a task topic in itself. (I am using the word “topic” here in the sense I defined in What is a Topic? What Does Standalone Mean?)
In many cases, however, accomplishing a task does not involve manipulating a machine — or at least, not manipulating a machine in a way that is specific to the task. A great deal of the technical documentation I have written over the years has been for programmers, where the product was a programming language, an API, or an operating system. People doing programming tasks use the same tools they use all day every day: editors, debuggers, compilers, etc. No one programming task makes any special use of these tools.
Creating rules to process an XML content stream and writing code to control shared access to a serial port are both programming tasks. They both use editors, debuggers, and compilers — but not in any way different from how these tools are used in every other programming task. Programmers do not need or want to be told how to type a function or set a breakpoint in every single programming topic in the doc set. Programming task topics, therefore, generally contain no procedures at all.
Most programming task topics are built around code samples, not procedures. Indeed, if you were defining a structured task topic type for a programming task, you would almost certainly make at least one code sample mandatory. But you would not make a procedure mandatory. Procedures are simply not relevant information blocks in a typical programming task topic.
Another common task type when you are writing about programming, and about operating systems in particular, is a configuration task. Getting the system configuration correct is vital to any OS-based project, but unless you have a GUI configuration tool, there are not usually any special machine manipulations involved. Configuration is generally done by writing a text file. It might be an XML file, or a file containing a series of configuration commands. In either case, the task of configuring a system has nothing procedural about it. In fact, it is almost all about planning.
Configuring an operating system correctly for a particular device is all about making the right set of trade-offs between functionality, size, speed, and security. A configuration task topic for any sub-component of a system is mostly a checklist of things to think about: how many communication channels will be required for different applications to talk to each other. How much memory will each application need? How much stack space? Just as a code sample is central to a programming task topic, a checklist is central to a configuration task topic. Procedures play little or no role in either one.
There can be much more to it than simply building a topic type around a code sample or a checklist rather than a procedure. Every operating system has an API. Programs written to run on that operating system call that API to interact with all the peripherals and components of the system. On a desktop computer, the entire operating system is generally installed by default (with perhaps some obscure exceptions), so the entire API is available to all programs. But on an embedded device such as a digital camera, a microwave oven, or the guidance system of an ICBM, the operating system is configured to include only those parts of the API that are necessary for the code running on the device. Embedded operating systems are packaged in thousands of separate modules, and the OS configuration that is actually loaded on any particular model of a device is probably completely unique to that device.
An autopilot must not only be able to steer round the mountain, it must guarantee to do it in real time. A programming task topic for avionics programming should deal with specific issues not encountered by most programmers.
Add to this that the device software on may devices is required to work in real time. That is, not only must the automatic pilot be capable of figuring out how to fly the plane around the mountain, it must be guaranteed to figure it out and execute the maneuver before the plane hits the mountain. Not only this, before the plane is allowed to fly with this software, the manufacture has to be able to prove, to a very strict standard, that the auto pilot software is capable of doing this.
This means that there are a great many things that a programmer of avionics software needs to think about that a regular programmer does not. Every programming task for an avionics programmer is complicated by considerations such as:
- Is this function supported by the version of the OS approved for this device? (Approving a new OS module might cost a million dollars or more!)
- Is this programming technique deterministic (meaning it will always function in the same elapsed time each time it is run)?
- Will this programming technique cause my code to run in a way that compromises the deterministic nature of other threads in the system?
These are really important questions, and if you are writing a programming task topic for a real-time embedded systems programmer, you need to make sure you treat these kinds of subjects in every programming topic you write. This is what information typing is, or should be, about. It is, or should be, about making sure that every topic of a particular type does the whole job it is supposed to do.
When people are making the case for technical communications, they often point to technical communication problems that contributed to notable accidents. This kind of information typing is a vital part of what you do to avoid those kinds of issues. Providing a mechanism for breaking content into chunks and reusing the chunks may save a company money on its technical communications budget, but it does little or nothing to prevent the errors and omissions that lead to user frustration (at least) and the catastrophic loss of life and money (at worst).
In What is a Topic, What Does Standalone Mean?, I made the distinction between what it means for a piece of information to exist separately (as a procedure block might), and to functioning separately (as a complete embedded systems program or configuration topic might). The standard, in other words is not reusability, but usability.
This is what topic-based writing and task topic types should be about, therefore: creating topics that function for the user by consistently and reliably enabling them to accomplish the whole of their real-world tasks. This is about a great deal more than procedures, and there is a great deal more at stake than reuse.
Reuse is an important goal, to be sure, and money saved by reuse can help improve docs in important ways, but reuse, both in its implementation, and in the content models that support it, must be a subordinate goal and a subordinate function to the real function of information typing, which is designed to enhance usability and reliability.
And real information typing, the kind that produces strongly typed topics that are guaranteed to do the job they were designed to do, can save you money in other ways, by increasing the opportunities for automation and reducing the content management overhead that can slowly cripple loosely-typed systems.
Structuring and writing a task topic for a particular domain, such as avionics system programming, is about much more than chunking procedures separately from the rest of your text. A task topic is not a procedure.
Image Copyright (c) 123RF Stock Photos.
That’s certainly true: A task isn’t a procedure. And in some cases, which you’ve enumerated, the best way to accomplish a task isn’t by following a procedure.
Nevertheless, in at least as many cases a procedure is the best way to represent a task in technical documentation. In a DITA task topic, a procedure is packaged with other supporting elements — such as prerequisites, context, examples, results, and what to do next. While it certainly is a mistake to equate task with procedure, I think that a well-formed task topic, with links to supporting conceptual and reference information, does a pretty good job of guiding a reader through most tasks.
Hi Larry. Thanks for the comment.
Perhaps I should not have focused so much on task topics that contain no procedures. Perhaps doing so obscured what is really the wider point, which is that there is more to say about any task than how to manipulate a particular machine used in that task. Even when a task topic does contain a procedure, the procedure is not the whole of the task topics.
A procedure may be part of what I need to do to perform as task, but it is seldom all that I need to do. In many situations, the mystery for the user is not how do I turn the knob, but how do I decide what setting to turn to knob to. Decision making, not execution, is where the difficulty lies.
Planning is often the most important part of a task, and the part that the user needs the most help with. Enumerating the various things that the reader needs to plan for in executing the task is often the most important part of the structure of a task topic.
Also, a complete task may involve manipulating more than one machine, and therefore the task topic may require two or three procedures. (One of the problems people run across when converting is that the content contains more than one procedure in a single section.)
So, my point is not that some tasks are procedures and some are not; my point is that a task is never a procedure, though some tasks may involve one or more procedures. A task topic should contain the content the reader needs to accomplish their goal. To equate a task topic with a procedure information block, as DITA does, is to obscure this point, a point which is fundamental to what task-oriented writing is supposed to be about.
I will explore more of what a task topic should really look like in a future post.
Thanks, Mark, for amplifying your remarks. I certainly agree that a task topic with only a procedure is almost never sufficient. That’s why good writers include contextual information, prerequisites, and so forth. That’s why the DITA standard includes those things as well.
> A task topic should contain the content the reader needs to accomplish their goal.
That ought to be irrefutable. But in practice it gets little thorny. What if — as often happens — you’re writing to a range of readers, some of them newbies some of them old hands? In that case, do we clutter up the task topic with content that the experienced reader has to scroll past? Or is it better to include callouts and/or links that can help the newbie while not slowing down the experienced reader? This is how I would do it in DITA.
Perhaps the best strategy is collapsible sections so that readers can read — or ignore — content as they see fit. This is the
progressive disclosure model. I think this approach has a lot of potential, even though it (obviously) doesn’t work in printed documentation and, admittedly, I don’t think DITA does it very well (yet).
Larry, you say it ought to be irrefutable that a task should contain everything that a reader needs to accomplish their goal. Yet I can remember sitting in a presentation in which a prominent DITA consultant took an article on some aspect of camera operation and showed how in DITA it should be broken down into 6 different topics. To actually perform the task with the camera, you would need all 6 of those “topics” in pretty much the original order, so clearly the approach of breaking the content into six separate chunks was not aimed at making sure each “topic” contained everything a reader needed to do the task. And I could point you at several examples of doc sets written in DITA in which the individual “topics” are not, for even the most hypothetically expert practitioner, sufficient to enable them to do their task.
The point here is not whether DITA makes it impossible to write good topics in the sense in which I use the word. DITA doesn’t make these things impossible, though it does in some cases make them more difficult than they should be. The point is about the attitude to topic typing and information typing in general, which DITA fosters with its confusion of topics and IM-style information blocks.
The basic problem is that DITA uses what it calls “topics” as both its only unit of information design, and as its only unit of reuse. If reuse demands more granularity than rigorous specification of a topic template, which one wins? No matter what is possible in theory, we know which one actually wins: reuse. And we see the too-frequent result: Frankenbooks.
The question of what an individual reader needs is, of course, an issue, and it is really a big part of what topic typing should address. What you see in many documentation sets is that this issue has been decided very differently from one topic, chapter, or section to another. One section goes into excruciating detail; the next skims the surface. The result is usually horrendous gaps in the information, and a horrendously inconsistent reading experience for the user.
This is actually one of the principal things that proper topic typing should address. It should reflect a decision about where to strike the balance across the information set, and it should demand from the writers that they supply everything that that decision requires be in a topic, and exclude, but reference, everything that should not. The issue is not what the topic type allows them to do, but what it demands that they do.
As for linking to ancillary material, and for implementing things like progressive disclosure (which I think is a great idea), the kind of topic typing I am talking about makes these things very much easier to implement. Given strict topic typing and the use of soft linking, you can generate those links automatically, and if each section and element of a topic type is specifically defined, you can implement progressive disclosure by algorithm.
The last thing you want, especially when creating content that may be presented in many different media, is to have authors including ad-hoc decisions about linking or progressive disclosure in the content source. Those things should be determined by an algorithm appropriate to each media based on the well defined information type information in the content.
True, we don’t want authors making ad-hoc decisions about linking or progressive disclosure….or, for that matter, about topic granularity or how to do reuse. Those are issues an information architect should be deciding. You’re concerned about a lack of standards or guidelines, and I agree. DITA is a toolbox, and writers need guidance on how best to use its tools.
However, I have to correct one thing you said: Topics aren’t the only unit of reuse in DITA. Reuse can be done at an element level (a step, for example, or a paragraph or a table) using conref or keyref. Again, it’s up to the information architect to set up the reuse strategy and make sure the writers know it. If writers are producing tiny, incomplete topics just so they can be reused, they’re not doing it right.
“The issue is not what the topic type allows them to do, but what it demands that they do.” I don’t think it’s the job of the tool (in this case, the way in which “topic” is defined) to enforce good practices. Instead, it’s the job of the information architecture.
Larry:
First, thanks for the correction. Indeed, DITA does offer other reuse mechanisms.
Second: You say, “If writers are producing tiny, incomplete topics just so they can be reused, they’re not doing it right.” I agree with you, but it is very clear that many DITA users are doing just this, and that many DITA consultants appear to be recommending they do just this. And DITA, by making a topic a unit of reuse at all, actively leads them down this path.
You say: “I don’t think it’s the job of the tool (in this case, the way in which “topic” is defined) to enforce good practices. Instead, it’s the job of the information architecture.”
Here is where we disagree most fundamentally it seems. In my view, it is precisely the job of the topic type to encourage and, as far as possible, enforce good practices. As far as I am concerned, the definitions of topic types are the core of the information architecture.
I have been through enough conversions of content to know that no matter how good or how thorough the writers are, when you actually define and apply a strict topic template to their content, they are amazed and horrified by the inconsistencies, omissions, and outright errors that are exposed as a result. We need these aids to achieve the levels of quality and consistency we are after.
Indeed, I would argue that if your information type is not doing this, it is not a “type” in any useful sense of the word. A type is a promise, and is defined by the things it promises. If it makes no firm promises, it is not a type. But that is a subject for another post.
I am missing some nuance here. Why is a procedure a “a set of instructions for manipulating a machine?” Why can’t it be a set of instructions for accomplishing a task?
Also, I use the word task more broadly than you do. A task can be an entire project (as in being tasked with leading an expedition to Mars) or it can be one small piece of the whole thing. Tasks can contain tasks.
So, what am I missing?
Hi Debbie. Thanks for the comment.
Great points! One of the frustrations of the blogging form is that it does not leave much room for elaboration and qualification. One of its delights is that you then get to elaborate and qualify in the comments!
You are certainly correct that as a literary form — a set of numbered steps under a heading — you can use a procedure to describe an entire task rather than just the manipulations of the machine. In practice, though, we don’t use it that way very often.
Consider a recipe. A recipe is a task topic, and it has a certain well established form. It has a title, which is the name of the dish, and optional introduction, a list of ingredients, a procedure for cooking the ingredients, and some optional notes on servings, nutrition, and wine or food parings.
The first step of the task of making this dish is to assemble the ingredients. But recipes don’t start out by saying:
1. Go to the market and buy some tomatoes.
2. Get some flour out of the cupboard and put it on the counter.
3. Go to the basement for a bottle of wine.
They simply start with a list of ingredients and assume that you know that you will need to get these ingredients if you want to cook the dish. They only use a procedure for those parts of the task that involve direct manipulations of tools and ingredients:
1. Heat the oven to 350 degrees.
2. Chop the tomatoes finely.
3. Pour tomatoes into casserole and sprinkle with salt.
Similarly, the recipe procedure does not detail the later parts of the task. It does not say:
13. Call the family to dinner.
15. Make sure the kids wash their hands.
This, I believe, is how procedures are typically used: for the mechanical manipulation parts of a task. The other parts of the task have so much optionality and variability in them that writing them as steps would either look absurdly vague or impossibly precise (as my steps for acquiring the ingredients illustrate).
In any case, my real point here is to say that the procedure alone does not constitute the totality or even the center of a task topic. There are many things that the person completing a task needs to know that are not best presented in procedural terms.
You are correct, too, that tasks can contain tasks. Tasks are fractal. Clearly it is not feasible to write one mega-task topic that covers the top level task, and, nested within it, all the lower level tasks to whatever level of nesting exists in the task domain. People do not think of their tasks that way either. So, you will need multiple task topics at different levels of generality, and those at a higher level of generality will need to make reference to tasks at a lower level of generality, to which they should presumably provide a link.
One of the things that a robust task topic typing can do is to provide different task topic type schemas for tasks at different levels of generality, thus assuring some consistency in how writers handle tasks at different levels, and making the documentation set more predictable to navigate.
I think here we’re up to something I wouldn’t have thought of in the first read. Generally I completely agree with your meaning of a task. But on the other hand I think tasks are more diverse, depending on the level of experience of the target group.
The lower the level of experience of your target group is, the closer a task gets to a procedure in general, if not being the same.
Let’s take your example of the recipe.
For some completely inexperienced users, the recipe would start like this:
Tomatoe soup – Getting started
1. Go to the market (down the road, see map A) and buy some tomatoes (see fig. 1).
2. Go back home.
There’s no room for options in there, as they would distract the completely unexperienced from the task at hand.
Now, if you deal with increasing levels of experience, you’re shifting your tasks to more sophisticated chunks of information:
Fusion – Getting started
Prerequisite is a high enough starting temperature in the fusion chamber, which can be achieved by several means (see figures A, B and C).
You see, the less details you have to provide, based on the experience of the reader, the farther you get from a task being a procedure.
Alex, thanks for the comment and my apologies for the delay in replying.
You make an interesting point about a task topic becoming less procedural the more expert the practitioner. That makes a lot of sense, at least as a generality.
Your example of the procedure for an extreme novice is also interesting because it illustrates that you really can’t write for the extreme novice at all. The kinds of instructions that the extreme novice needs can only be given personally by someone familiar with the novice’s entire context. It is only when the novice has learned enough to contextualize instructions for themselves that they can actually learn from a book.
Pingback: The Real Docs Need is Decision Support - Every Page is Page One