11 Responses to A Task is Not a Procedure

  1. Larry Kunz 2012/08/07 at 15:54 #

    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.

  2. Mark Baker 2012/08/07 at 17:04 #

    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.

    • Larry Kunz 2012/08/07 at 17:41 #

      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).

      • Mark Baker 2012/08/07 at 19:50 #

        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.

        • Larry Kunz 2012/08/08 at 10:26 #

          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.

          • Mark Baker 2012/08/08 at 10:59 #

            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.

  3. Debbie M. 2012/08/09 at 14:14 #

    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?

    • Mark Baker 2012/08/09 at 16:16 #

      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.

      • Alex Knappe 2012/08/10 at 01:52 #

        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.

        • Mark Baker 2012/09/06 at 22:28 #

          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.

Trackbacks/Pingbacks

  1. The Real Docs Need is Decision Support - Every Page is Page One - 2012/11/05

    […] by way of task support are simply procedures for operating machines. But, as I have argued before, a task is not a procedure. In many cases, the support people need to complete their tasks is not information on how to […]