16 thoughts on “Where Topic-Based Authoring Fails: End-to-End Scenarios

  1. Patty Blount

    Tom, again, your timing is impeccable. We are JUST beginning an effort here similar to your end-to-end scenario organization. We’re calling it User Relevant Content but the goal is the same: to produce content that is self-contained, modular, and provides just the information a user needs to solve a particular business problem.

    The point you made about how difficult it is for users to see how tasks are used in combination with each other was driven home for me when I worked on our SAP implementation.

    One of the courses I was developing was to create product codes for the ordering system. The course was comprised of a series of product code creation tasks. When we piloted the course, it was instantly clear we’d missed something – users need to know how to combine the various tasks to achieve a goal such as Create an Electronic Product Code is very different from Create a Physical Product Code, even though the same core tasks are involved. We had to scrap the course and redesign it based on the pilot results. Version Two contained flow charts and job aids that illustrated how to combine the four, five, or even ten tasks necessary for achieving a goal.

    Thanks for giving me some ideas as we learn to implement our URC plan.

    1. Tom Johnson

      Patty, thanks for the example you shared. It’s good to know others out there are on the same wavelength as me with some of these strategies.

  2. Ann Rockley

    I don’t think that topic-based writing and end-to-end scenarios are mutually exclusive. Instructional designers chunk information up all the time to provide modules, sub-modules, exercises etc. They provide sequential learning which builds on the previous topic/lesson.

    We need to think about how a person is using the information at a particular point. In a learning scenario, you probably want sequential topics, in a specific task scenario you probably want stand-alone topics. Stand-alone topics can reference preceding and following content through related links. You can tag content to say “these topics must always go together” if you are doing dynamic assembly of content if they cannot stand on their own.

    An example I used today in my presention at Congility 2011 on Developing an Intelligent Content Strategy, I had a medical devices client that had a wizard to help set up the product. The content was presented as a single task and covered 25 pages. At first glance it didn’t appear as though there were sub-tasks that could stand on their own. After analysis it became clear that there were in fact multiple tasks associated with the wizard and that some of those tasks were required as stand-alone topics in other guides (e.g., if you wanted to go back and change the date/time format). Even if there weren’t stand-alone tasks we would have chunked it, 25 pages is simply too long to keep going and going without some sort of cue as to what you are doing (e.g., a title).

    I agree that if you simply retrieve content based on metadata and the author has not specified that certain topics must stay together when retrieved, the context and meaning of the content could be lost.

    1. Tom Johnson

      Ann, thanks for commenting. I agree that we should look for ways to link tasks together, and define prerequisites and follow-up steps where necessary.

      What I’m trying to articulate in this post are processes that are entirely unique. Illustrator lends itself well to these, since knowing how to use the brush tool or the pen tool doesn’t really mean I can create a masterpiece, just as knowing how to use a paintbrush doesn’t mean I can actually paint a compelling picture. So knowing how to use a tool and knowing how to illustrate can be two different tasks. Bringing together the how-to steps for using each tool wouldn’t necessarily address the complexities of painting a figure standing in a field, for example. Sure I may know how to draw a oval with the pen tool, and outline a body with the brush tool, but how do you actually make someone look human? That kind of instruction would be an end-to-end process whose explanation wouldn’t work by simply linking up how to use the pen and brush tool.

      1. Ann Rockley

        You are absolutely correct, we can tell someone how to do something but we can’t necessarily teach them the skill to use the software/tool etc effectively. That is not uncommon in our work though. Skills can’t usually be taught with just textual guidance.

        I know this sounds cliche but a number of years ago I worked on a project for a 3 dimensional imaging device. It was used to image the brain prior to surgery then used in surgery to guide the surgeon. I could tell them how to get the image, resolve the image, and even provide suggestions for getting the best image, but I certainly couldn’t explain how to conduct the surgery.

        I’ve also worked on projects where we provide simply the how to tasks and then provided “cookbooks” to illustrate how to use the product in the context of a real example. The how to was woven between the example. It was modular and we used conditions to filter out the example content when not required.

        Maybe I’ve just been writing modules for too long, I am having a hard time seeing when modules wouldn’t be appropriate.

        1. Tom Johnson

          Brilliant example with the brain surgery. That describes the situation perfectly.

          I haven’t worked much with modules, but I can see how the how-to would weave back and forth with the example.

          Overall I think this thread points to the need for more real-life implementation of the information we create. I get so mired in the how-to for each “task” I write — I often forget to see the larger reality of the complex problems users encounter.

  3. Mark Baker

    Hi Tom,

    I have a few issues with this.

    1. We have to make a distinction between task support content and tutorial content. A tutorial supposes a willingness on the part of the user to sit through the entire tutorial. This supposition may be will founded or ill founded, but once you have decided to do a tutorial, that tutorial is one object. Breaking it up into smaller pieces is not topic-based authoring, it is simply a mistake. (Some tutorials may require the outputs of other tutorials as inputs, which does not make them one tutorial. Dealing with the inputs to a task is a different issue, which is my next point.) Topics are not defined by length, but by singleness of purpose.

    2. Every task has dependencies. The classic task topic is a recipe, and every recipe starts with a list of ingredients. The implicit (or sometimes explicit) first step of a recipe is to gather the ingredients.

    In many cases, the ingredients of one recipe are actually the product of another recipe. There are often multiple ways you can get hold of those ingredients. Suppose that a recipe calls for beef stock. You could buy canned beef stock, you could make it from stock cubes, or you could make it from scratch. Making from cubes and making from scratch both involve recipes. You discover your need for those recipes by going through the list of ingredients of the first recipe.

    A really helpful recipe may point you to the different sources for obtaining, or recipes for making, beef stock. This is what a task topic in a topic based documentation set should do. Every task should begin with a checklist of necessary inputs for this task. If there are items on the checklist which are created by tasks that are described in topics in your information set, then the checklist should contain links to those topics.

    The main problem that people have with topic based writing is that they fail to think through what a topic needs to be like in order to function as a topic — in order to work as page one for the reader. Simply breaking down long-chain documentation into pieces and then expecting readers to reconnect the links for themselves is unreasonable. It also flies in the face of why we moved to topic in the first place, which was because readers won’t read the long-chain docs.

    3. It is not just about metadata, or at least, it is not just about search. I recently wrote about how technical documentation typically neglects the surf aspect of web navigation (here: http://everypageispageone.com/2011/05/17/search-browse-surf-pick-three-and-add-something-extra/). Search is about how you find a starting point in the content. After that, the user should be able to surf through ancillary content, including, if necessary, linking to task topics that describe how to create the missing ingredients of the task they really want to perform.

    Users are goal oriented. Traditional long-chain documents bury the goal and frustrate the user. Typical contemporary topic based approaches expose the goal and bury the prerequisites, again frustrating the user. Reverting to long-chain documents is not the solution — we know users don’t read them. The solution is to get better at writing topics.

    1. Tom Johnson

      Mark, thanks for your reply — insightful as always. I especially like the distinction you make between tutorial content and task support content. That makes sense to me.

      In the tutorial, I assume one would link out to specific task support topics for more detail. For example, in Deke’s black cat tutorial, he uses gradients. The tutorial could link to the gradient task support topics for more information rather than reteaching users how to use the gradient tool in the tutorial video. I like that approach. His use of gradients in the tutorial is specific to making cat eyes, which apparently have their own gradient approach.

      1. Mark Baker

        Hi Tom,

        Yes, I think that is a good way to handle tutorial material. One of the problems with tutorials is to hit the balance between reader doing and writer explaining (which means reader reading rather than doing). The ideal, it seems to me, is to keep the reader doing as much as possible, while being ready to support them with more detail when they decide they need it. By keeping the tutorial topic lean and action oriented, and making more in-depth material available through links, you let the user choose when they want to deep dive the details. A side benefit is that the tutorial looks less daunting.

        There is a larger point that is running through this discussion, though. In linear media, like books, we very commonly encode information about the relationship of tasks in the order of the book itself. If you simply break a book up into independent topics, you lose the information that was encoded in the order of the book.

        Sometimes when people realize that this information is missing, they conclude that they have to recover it by stringing the topics back together in a required order. But this is neither the best, nor the only way. A better way is create new topics that describe the relationship between tasks, and link them to the topics that describe those tasks.

        I think there are three principle advantages to this:

        First, there is often more to be said about the big picture than can be implied by a sequence of lower-level tasks, and this creates a place to say it.

        Second, readers will only get the big picture that is implicit in the sequence if thy are alertly reading the whole sequence in a single sitting, which, we know perfectly well, they almost never do. Here the big picture is presented in a concise and explicit topic that they can more readily grasp, and that does not exhaust their patience.

        Third, except in the artificial case of a tutorial, there is almost always more than one possible sequence in which the task might be performed (not to mention more than one person who may perform them). When a linear treatment imposes one predominant sequence, it is at the expense of the other possibilities, which are either neglected or are handled by awkward branches and cross references in the main sequence.

        Non-linear media solve a number of problems. But we can’t expect to simply fragment content written for linear media and have it work in a non-linear environment. We have to write differently for this environment.

        And I think we have to take the surf component of web navigation much more seriously than we do at the moment if we are going to make this work. I am particularly distressed when I read about people actively removing links from content in order to make it more easy to reuse. Linking is what makes non-linear media non-linear, and when we remove it, we are effectively going back to the linear organization of content that we had before.

        There is a scene in the Star Trek movie, The Wrath of Khan, in which Khan is beating Kirk in a tactical duel of starships, until Spock points out that while Khan is tactically brilliant, he is thinking in two dimensions. Kirk is then able to beat Khan by maneuvering in three dimensions.

        Too often, I think, we are moving to topics, but still thinking in two dimensions. We need to start thinking in three dimensions if we are going to realize the full potential of the new media.

  4. Christine Astle

    Tom, I think you summed it up well in the last sentence. The power of topic-based, modular authoring is that it can do both. Once you have the modular topics, associated with meaningful metadata, you can retrieve that piece based on the metadata (either through search or a more dynamic retrieval based on the user’s context) or you can create a scenario-based map that guides them through the topics in a particular sequence.

    1. Tom Johnson

      Thanks Christine. This topic has a lot of depth. There are so many ways to approach help content, and as you say, they aren’t exclusive approaches. One can provide a variety of paths for users.

  5. Jim Campbell

    Hi Tom,

    An interesting project that I just learned about recently is the Adaptable Gimp project. They’ve taken the interface for the Gnu Image Manipulation Program and have re-engineered it to accommodate end-to-end task sets.

    The tasks sets are actually contributed by users. There’s a video on it available here: http://www.adaptablegimp.org/w/Welcome_to_AdaptableGIMP

    I’m not sure how well an application like this would scale (not to say it couldn’t, but I’m just not sure on the matter). Also, I’m not sure how the task sets get integrated with the application (are the bundled at build time? Are they stored on a server? Can you add them locally?).

    It certainly is an interesting approach, though, and it just happens to coincide with the topic of your blog post.

  6. Jim Campbell

    A bit more info… from the project website: “What is unique about AdaptableGIMP is that all task sets are automatically shared with the entire user base: Once you create a task set, it is uploaded to the wiki for all to use. This allows the community to collectively learn from each other.”

    I’m unclear on any editorial review of the task sets. It’s still a neat project, though.

    By the way, I seem to recall you mentioning somewhere that you didn’t understand why people would use Linux. This project, as well as the projects that I’ve linked-to before all come from Linux-based free software projects. We’re behind in some areas of creating innovative user help, but are learning, growing, and are trying to put best-practices into practice.

    1. Tom Johnson

      Jim, thanks for pointing me to the Adaptable Gimp video. How interesting. I’ve never seen anything like that — it certainly addresses the topic of my post head on. I’ll have to check it out more.

      Re Linux, my blog is hosted on a Linux server. I can’t remember exactly what I said about Linux, but I’m not against it. As for open source tools, though, I think people are often better off spending time learning industry standards rather than open source alternatives — at least careerwise. Of course, if you create a good portfolio, the toolset becomes less important.

  7. Jonatan Lundin

    The black cat tutorial scenario sound like, what I call a Meaningful Result Statement (MRS) in SeSAM. Every technical product can deliver meaningful results to the user. To make the product deliver the result, the user has sometimes to use the product (as when using illustrator to make a cat image – the cat image is a meaningful result for the user).

    For some other MRS, the user is not involved; the result is delivered when a certain set of conditions are met. For example when an alarm is given when the monitored temperature is above or below a set value.

    When documenting technical products, software, machines or whatever type of products, the technical communication approach should be to first model the meaningful results the product can deliver. After all, a product is brought to the market place to help a user solve a need, problem or requirement. What needs, problems or requirements can your product help the user solve?

    The task (topic) information you need to develop is derived from the meaningful result statements. For example;
    * What does the user need to do before putting the product in normal operation, to allow it deliver the result (maybe some configuration is needed)?
    * How is the user working with the product during normal operation to make it deliver the results?
    * How does the user ensure that the product has delivered the results (where to look if the result is not immediately visible after using the product)?
    * How does the user find the reason to why the product has not delivered the results (if the user has concluded that a result was not given – maybe the product was set up incorrectly).

    The answers to the above questions are meaningful set of task topics. A task topic must be included in a meaningful context; the user is doing the task to achieve meaningfulness (=solve a need, problem or requirement). Just do a task because it is fun is not meaningful.

    Each meaningful result the product can deliver can be described from various angels; one important is the possibilities to customize it to make the product adaptable to various user contexts. What can be customized? How does the user calculate/plan how the product must be set up to adapt it (should I set setting X to 10 or 20 in my case)?

    For those interested I’ll be giving a presentation about SeSAM on NLDITA 2011 (1th of June) in the Netherlands. The presentation will be upload to YouTube shortly.

  8. Tom Johnson

    Jonatan, thanks for joining the discussion. I like the term “Meaningful Result Statement,” even though it sounds a bit vague and formal. The part I like is the “meaningful” aspect, because a set of task-based topics may not mean a whole lot to the user if they don’t connect to something the user is trying to do.

    With the example of Illustrator, there are so many uses of the application (you could draw a cat, a building, a diagram, etc.), the help can’t cover all of these uses. So it’s not feasible to come up with a list of tasks the user might do — they could be nearly infinite. But if you can create a few tutorials that show how the various tools and tasks work together toward some end, that would be meaningful to the user.

Comments are closed.