Confusing Analytic and Synthetic Truths in Defining Topic Types

Ray Gallon’s recent post, Let’s Break a Tech Comm Rule proposes that we should rethink the idea of separating tasks from concepts. Hooray! It’s no secret that I’m no fan of this separation.

Reading Ray’s post, also sparks this thought. It is a common and sometimes catastrophic error to confuse an analytic truth with a synthetic truth. That is, it is an error to confuse a truth about how to analyse something into its parts with a truth about how that thing should be organized and presented to users.

Take pizza for example.

You can analyse Pizza into crust, sauce, and toppings, but you serve it by the slice. The same principle applies to concept, task, and reference information. Image courtesy of Suat Eman / FreeDigitalPhotos.net

You can analyse Pizza into crust, sauce, and toppings, but you serve it by the slice. The same principle applies to concept, task, and reference information. Image courtesy of Suat Eman / FreeDigitalPhotos.net

An analysis of pizza reveals that pizza essentially consists of three parts:

  • crust
  • sauce
  • toppings

There are hundreds of different pizza recipes, but all of them consist of crust  sauce, and toppings. This is an analytic truth about pizza. It is not the only way to categorize the things that go into pizza. It is also an analytic truth that pizza contains the four food groups, grains, meat, vegetables, and dairy. But that it consists of crust, sauce, and toppings is, nevertheless, a useful analytic truth about pizza.

Similarly, it is an analytic truth about technical content that it consists of concepts, tasks, and references. There are other ways of analyzing technical content, but concept, task, and reference definitely have analytic value.

What synthetic truth can we derive from these analytic truths? In the case of technical content, many have reached the synthetic conclusion that concepts, tasks, and references should be presented to the reader separately.

How would that stack up in the pizza world? The parallel conclusion would be that diners want their crust, sauce, and toppings served separately, as separate courses, or at separate restaurants.

Clearly this is not true of pizza, so why would we think it is true of content?

We could make the case, I suppose, that concept, task, and reference represent different reasons for readers to use content. Concepts are used for learning, tasks for doing, and references for looking stuff up. That’s reasonable enough. But what makes us think that readers do these three things separately? Why would we think a user would want to do a task without looking anything up? Why would they want to learn something about a product or a tool unless they had some task to do with it? The fact is that learning, doing, and looking stuff up are highly related and integrated activities that work together to get stuff done.

Given that they are highly related activities, there is analytic value in recognizing that they are supported by different kinds of information. For instance, we could use this analysis to audit content to make sure that when a concept is mentioned in a procedure, there is adequate conceptual material present to support it, or that if a procedure requires you to enter particular kinds of information, there is at least some guidance on where to look that information up.

The analysis, in other words, can be useful to verify that the synthesis has been done properly, that the diner is being served a pizza which has crust, sauce and toppings. But the rules of synthesis are not contained in the analysis of parts. It requires a different kind of knowledge to know that the crust goes on the bottom, the sauce in the middle, and the toppings on top.

In fact, the rules of synthesis — the art of synthesis — is much more subtle and complex than the rules of analysis. We see this in many fields. Professors of English don’t generally make great novelists, nor critics great actors or directors. The art of dissection is not the art of construction, nor the art of creation. You do not learn synthesis by practicing analysis.

Of course, we must not overlook the fact that technical communication is a commercial pursuit, not a literary one. Companies have a legitimate interest in ways of increasing productivity and improving consistency in the technical content they produce. Breaking down content into small structured units is a good way to improve consistency and productivity. (The benefits are non-trivial, and consistent across many fields, as a study of the Lean Thinking movement or of agile software development will demonstrate.)

It was clearly tempting for tech writing organizations in search of a way to break content production into smaller units to turn to an existing analytic framework like that provided by information mapping. But in turning to task, concept, and reference as analytic categories, we missed the fact that useful content is not created by separating these categories but by fusing them together in the correct way.

The fact of the matter is that there may be a generic analysis, but there is no generic synthesis. All pizzas can be analysed into crust, sauce, and toppings, but the way you combine specific ingredients to make a specific style of pizza is far more complex and more varied.

Woman eating pizza

A topic should be like a slice of pizza. Small enough to hold in your hand, but containing all the ingredients. Image courtesy of imagerymajestic / FreeDigitalPhotos.net

Every Page is Page One topics provide another approach to creating content in smaller units, and to distributing the content creation responsibilities for greater consistency and efficiency. Happily, Every Page is Page One topics also suit the way readers consume information on the Web.

One of the key characteristics of Every Page is Page One topics is that they naturally tend to conform to a type. You can use structured writing techniques to define the type of an Every Page is Page One topic, and to ensure that it contains the appropriate types of concept, task, and reference material, in the right places, and in the right quantity, either inline or through linking. You can even use task/concept/reference analysis to help figure out what that combination should be.

But when you serve pizza, serve it by the slice, not one layer at a time.

 

, , , , , , ,

34 Responses to Confusing Analytic and Synthetic Truths in Defining Topic Types

  1. Helen Abbott 2013/01/08 at 20:44 #

    Thanks Mark! You’ve summed up beautifully what I’ve been musing about for the last while, and struggling with in one particular project I’m working on right now. I had just decided to ditch the separation between task, concept and reference material and your post helps me understand why it’s the right decision. This one’s a keeper.

    • Mark Baker 2013/01/09 at 11:08 #

      Thanks Helen. Glad you found it useful.

  2. Ray Gallon 2013/01/09 at 05:02 #

    Mark, thanks for mentioning my post in this one. It clarifies perfectly why the separation is artificial. Even more importantly, the synthesis is actually the best, easiest, and fastest way to learn, according to cognitive science. That’s what I’ll be dealing with in my webinar series adobe.ly/T9bnW4

  3. Leigh White 2013/01/09 at 10:29 #

    Hi Mark,
    I’m scratching my head a little at this one, wondering if I have missed something because it seems so self-evident. Particularly, the statement “…we missed the fact that useful content is not created by separating these categories but by fusing them together in the correct way.” To me, the point all along has been not to separate the information just for the sake of separation, but to separate it in a careful and well-planned way that ensures it can be fused together in the correct way. Or better, in several correct ways. At the same time, there is potential value in the information as separated. To continue your pizza analogy, consider that we are baking the pizza (a prerequisite to serving it, surely!). It’s quite logical to separate the preparation for the crust from the preparation for the sauce from the preparation of the toppings. Then, of course, after all three have been prepared, they must be assembled, but there is separation within the process…or some processes, depending on what they are. If someone wants to know how to bake a pizza crust, I shouldn’t give them instructions on making an entire pizza. On the other other hand, if they do want instructions on making an entire pizza, I should be able to give them that. Proper separation of my information ensures I can do both. If they want an actual pizza, we should go out because I’m no cook!

    • Mark Baker 2013/01/09 at 11:05 #

      Thanks for the comment, Leigh.

      I think that may well have been the original intention. Certainly it is the idea behind information mapping — that you write in blocks of different types and connect them together into a map. In IM, though, this is more of a planning/design tool. IM does not necessarily involve writing pieces separately and then assembling them in different ways. It is a theory of information mapping, not information chunking. In fact, one of the criticisms that IM folk have of DITA is that DITA lacks a theory of how to put the pieces together.

      The lack of that design theory may be the problem, leading people to believe that merely doing the separation is the whole of the design effort.

      There is, of course, nothing to say that you can’t chunk your content according to a concept/task/reference scheme and then assemble it into a coherent whole with good narrative flow. But it turns out not to be so easy, especially if you are looking to do extensive reuse. It is little wonder, then, that what actually comes out of these efforts is often an artificial separation of information types and no narrative flow. The synthesis task is much harder and more involved than the analytic task.

      That aside, what now seems to be commonly accepted as conventional wisdom in tech comm, whether it is based on a misunderstanding or not, is the idea that the separation of concept/task/reference is a design ideal that is good for the reader. The analytic idea has become the synthetic idea, and that is just wrong.

      It is also commonly accepted that the only way to chunk content for more efficient creation and better consistency is to separate it into concept/task/reference, and that is just wrong as well.

  4. David Singer 2013/01/09 at 11:08 #

    Aside from the fact that some pizzas (3-cheese pizzas, for example) are made without sauce, I like the analogy you’re using.

    It’s clearly beneficial to include within a procedure any conceptual information that will help the user complete the task at hand. Giving priority to conformance with a schema rather than focusing on users’ needs is never a good idea.

    I’m concerned that in the paragraph in which you state, “It was clearly tempting for tech writing organizations in search of a way to break content production into smaller units to turn to an existing analytic framework like that provided by information mapping…” may convey the impression that task, reference and concept are part of the Information Mapping schema for content analysis. While “concept” is indeed one of our information types, “task” and “reference” are not. Of course, I recognize these three terms as DITA’s “terrible troika” of topics, but some readers may not. And as you’ve stated, DITA has little to offer in the way of information design theory.

    • Mark Baker 2013/01/09 at 11:18 #

      David,

      Indeed, you are correct to point out that the concept/task/reference troika is not part of IM. IM has a much more subtle and sophisticated set of information types. DITA’s reduction of information types to the troika is in itself an indication of DITAs greater interest in the mechanics of document production rather than sophisticated information design.

      Regarding, “Giving priority to conformance with a schema rather than focusing on users’ needs is never a good idea.” I would demur somewhat. If the schema were designed specifically to focus on the user’s needs, based on well informed knowledge of those needs, then conforming to it, rather than the writer substituting their own potentially less well informed judgement, would be a good thing.

      Alas, most schemas used in tech writing today are built not to express the user’s needs, but to meet the needs of the publishing engine. One of my principles of markup design is that the writer should not have to know anything about how the publishing engine works. The job of the authoring schema is to ensure that the writer provides what the reader needs. Nothing more. Nothing less.

  5. Marcia Riefer Johnston 2013/01/09 at 13:30 #

    Mark and Ray, Thank you both for the interblog conversation you’ve sparked. The pizza analogy brings the point home beautifully.

    I’ll borrow here from my comment on Ray’s post: a yarn metaphor also comes to mind. Information typing helps writers untangle concept, task, and reference material (or whatever types your organization uses). But untangling isn’t the goal. It just shows you what you have to knit with.

    • Mark Baker 2013/01/09 at 14:05 #

      Thanks Marcia,

      The yarn metaphor is another great example of why analysis is not a substitute for synthesis, or for design.

  6. Laurie Nylund 2013/01/09 at 15:10 #

    Being something of a workaholic, many things outside the obvious tools and resources of a freelancer (computer, software, Internet, etc.) get connected in my mind to my work. Now, I have to add pizza to that list…

    An excellent analogy though, and one I think will be useful in considering how to structure content going forward. Too often, I only get to update a piece that already has years of “structure” built in. I generally end up just following the style that already exists. After reading your column (with so many thoughtful posts like this one!) for the last few months, I think that I will now make a greater effort to convince my clients that there is a better way – and using the pizza analogy may just do the trick.

    • Mark Baker 2013/01/09 at 20:36 #

      Laurie, thanks for the comment.

      One of the most difficult things about working in the book model in tech comm is that so much of the time we are updating rather than writing from scratch, and when we have to add new information, or correct old information, we are are left trying to fit it into an increasingly eccentric and rickety structure because we simply don’t have the time, or sometimes the scope, to restructure the whole book properly. Of course, the reader doesn’t fare much better trying to navigate the result.

      One of the virtues of an Every Page is Page One information design is that you are dealing with units that are small enough to fix when they need fixing, and independent enough that you don’t have to worry about breaking something else when you do fix them.

      Certainly hope that the pizza analogy works for you in talking to your clients.

  7. Myron Porter 2013/01/09 at 18:07 #

    Analysis and synthesis in writing . . . hhhhmmmm. My background in business and technology– and in literary criticism, fiction and philosophy–demands that I must use form and function, consciously or intuitively. This is usually accomplished by a process analysis and synthesis.

    Try “The Underground Grammarian” to experience some extreme aspects of both.

    “The medium is the message,” McLuhan
    “A poem must not mean/but be,” MacLeish
    “Where is the man who has forgotten words? He is the one I want to speak with.” Chuang Tzu
    “We murder to dissect,” Wordsworth

    • Mark Baker 2013/01/09 at 20:23 #

      Myron, I think we can safely conclude that every useful piece of work is accomplished by a process of analysis and synthesis. It is when we do the analysis and stop that things fall to pieces.

      • Myron Porter 2013/01/16 at 12:01 #

        Mark, Understood. But, this may be a situation where proponents believe that the analysis IS the synthesis.

        This knife can cut in many directions, but any writing process is such a blend of skills and constant choices (both analytic and synthetic) that lines become blurred. Models or methodologies, such as DITA or EPPO, offer a way to clarify and compartmentalize. The core issue appears to be finding a model or methodology that is best suited to the task at hand. These will always be approximations, no matter how accurate or useful, because the process of synthesis is unlikely to completely submit to analysis.

  8. Joshua Wulf 2013/01/09 at 19:45 #

    Technical writing is not pizza making, it’s pizza recipe writing. Here’s a clear example of the value and application of the separation of concept (ingredients) and task: http://www.taste.com.au/recipes/12039/chicken+brie+and+spinach+pizzas

    • Mark Baker 2013/01/09 at 20:21 #

      Hi Joshua. Thanks for the comment.

      I’m not sure how a list of ingredients counts as a concept. What is conceptual about it? If anything, isn’t it more like a reference?

      And even if a list of ingredients is a concept, how does a recipe separate them from the instructions? The two are clearly presented together in the example you provide. The recipe would clearly be less useful if the ingredient list and the cooking instructions were presented in two different topics.

      To be sure, there is virtue in the long established pattern of a recipe listing all the ingredients first, and then giving the list of steps, rather than just giving steps and forcing the reader to pick the ingredients out of the steps. But it did not take DITA or information mapping to discover that this was a good thing. It is, though, a good example of the kind of thing that IM talks about: creating a single working document by the appropriate combination of information blocks.

      You will note that I did not deny the analytic value of the separation of information types. In fact, I acknowledged it. In many cases, the analysis can lead to the creation of a better synthesis by helping us recognize all that should go into a useful synthesis. But it is the result of the synthesis, not the analysis, which is useful to the reader. It is when the analysis gets mistaken for a principle of synthesis that we get into trouble.

      A recipe is a great example of an Every Page is Page One topic, and it illustrates for me the principle that what makes a good EPPO topic type is a particular mix of information blocks (to borrow IM terminology) suitable to a specific purpose.

      In fact, the recipe really seems like concrete proof that you cannot successfully separate concepts from tasks. Neither the ingredient list alone nor the procedure alone would be of use to anyone. They only work together.

      And from a reuse perspective, neither one is reusable without the other. You are unlikely to find another procedure that works with the same ingredient list, or another ingredient list that works with the same procedure. They are two types of information, to be sure, but they are inextricable joined together and of no use when separated. No purpose would be served by separating them at the authoring stage, and no purpose would be served by presenting them separately to the user.

      • Alex Knappe 2013/01/10 at 08:01 #

        Mark, this is where I have to intervene.
        A recipe is just the perfect example for the use of differentiating topic types.
        The list of ingredients is a reference. It can stand alone (as a shopping list i.e.) or in context with (multiple) tasks.
        A simple example here would be the following two recipes:

        Ingredients:
        – 500g tomatoes
        – 200g mozzarella
        – fresh basil
        – Pepper, Salt, Balsamico Vinegar

        Recipe 1: Tomato Soup with Mozzarella and Basil
        Recipe 2: Insalate Pomodore con Mozzarella e Basiliko
        Recipe 3: Pizza Topping – Classic Italian

        As you see, there’s a multitude of Recipes using the same list of ingredients, and the list also could be used in different context as a shopping list, or as reference data to enter into weight watchers online.

        It clearly would make sense to differentiate between reference and task here.
        The task itself could also be written in a way here, to fulfill the requirements of reuse: Chop the vegetable and cheese into the desired size and put it onto a plate. Add the spices. Serve with red wine.
        This task could be reused with other vegetables than tomatoes (best examples here are the steps to create sauce hollandaise and sauce bernaise, which are essentially the same).

        But I agree, that the terrible troica in itself with no “rules of engagement” is far from being the sole salvation.

        • Alan Brandon 2013/01/10 at 10:20 #

          Mark, Alex,
          I think this highlights a terminology issue. DITA calls everything a “topic”. IM calls the elements of a topic “blocks” (which are arranged in “maps” etc). So the list of ingredients is a reference topic/block, depending on how you look at it. Whatever you call it, it is a good candidate for reuse (as a shopping list, in other recipes, etc).
          I think the key is that reference content should be separated from task/procedure content as Judy describes below, even though they may be presented together in one recipe “topic”.
          The “concept” about pizza being crust, sauce, and toppings is not needed in the recipe, unless it is part of a tutorial for example. Only beginners would need that info.

          • Mark Baker 2013/01/11 at 13:54 #

            Alan, thanks for the comment. You are absolutely correct about DITA terminology and the problems it causes to use the term “topic” for everything. This is largely why I have found it necessary to coin the phrase Every Page is Page One topic — to emphasize that I am not talking about what IM calls “blocks” and DITA, unfortunately, calls topics.

            When you say ” the key is that reference content should be separated from task/procedure content”, what do you mean by separated?

            * Placed in different files by the author?
            * Displayed on different pages to the reader?
            * Be separate information blocks within the document (to use IM terms).

        • Mark Baker 2013/01/11 at 13:49 #

          Alex,

          Surely you are not seriously suggesting that cookbook authors should actually write ingredient lists separately from the instructions in the event the ingredients lists happen to match? What would be gained by that?

          When I talk to people about reuse, I always warn them to make a distinction between reusing information and reusing text. If you have $1,000,000 in your back account and I have $1,000,000 in my bank account, that is a case of the text being the same but the information being different. If I spend $500,000 on a yacht, you don’t want the bank to debit $500,000 from your account as well.

          The same list of ingredients between two recipes is a case of same text, not same information. Reusing text that is coincidentally the same, but represents two different pieces of information is a recipe for content management problems and accidental introduction of error.

          As far as abstracting a shopping list from a recipe, you don’t need to separate the ingredients list from the preparation steps to do that. All you need to do is to mark up the ingredient list as an ingredient list so that you can pull it out of the recipe file when you need it.

          The whole point of structured markup is to provide addressability of content below the file level. You do not need to separate content into different files to make the parts of that content addressable for processing.

          • Alex Knappe 2013/01/14 at 07:56 #

            The distinction between text and information is exactly what bothers me here. It is the context that separates the list of ingredients from the task of cooking.
            How do you define information? It’s either self sufficient (like an EPPO topic), or it is a block of text that is able to be referenced by multiple contexts.
            This is what I call the distinction between (more or less) generic and specific information.
            While a recipe is of the specific information type (and represents perfectly an EPPO topic), the generic information type is more on the border between pure text reuse and information.
            Specific information is able to contain generic information, while generic information never contains specific information.
            The list of ingredients is a generic block of information, because it may stand alone in the first place (when you open your fridge).
            A task usually contains more than only the steps to do something (context, prerequisites, steps, goal, result) and is of the specific information type.
            References may contain generic OR specific information.
            DITA itself doesn’t help you much with deciding what chunk of text represents a piece of information or is simply a block of text.
            It is even hard for an author to decide what is information and what is not.
            My personal definition of generic information is, that it can create context by itself. It isn’t tied to a specific piece of other information.
            There’s never only one recipe, you can create from a set of ingredients.
            This is also where the discussion of granularity begins. Is the single ingredient already a piece of information?
            For some applications it would certainly be the case. There are cookbooks based on one ingredient (i.e. potatoes). Seasonal cookbooks also use ingredients to specify the recipes contained.
            While the same piece of text can be simply reoccuring text for one party, it may be a piece of generic information for another party.
            While a list of ingredients can be reoccuring text for one cook, it can be a central piece of generic information for the other one.
            It’s up to the information design to define what is information and what not (and hence is packaged into the corresponding structures).

  9. Joshua Wulf 2013/01/09 at 21:24 #

    You can automatically generate a thesaurus / vocabulary from your concept topics [1], then use semantic enrichment to automatically link them to occurrences [2] (or suggest links to authors).

    So staying with the pizza example, each ingredient in your ingredients list can be (automatically) hyperlinked to a description of that ingredient (concept).

    [1] http://www.atmayogi.com/2012/12/creating-a-skos-vocabulary-using-open-refine/

    [2] http://stanbol.apache.org/docs/trunk/scenarios.html

    • Mark Baker 2013/01/09 at 21:42 #

      Joshua,

      I’m sure these things are true. I’m all for the automatic generation of content and links. But I don’t see how this is relevant to the present discussion. Links are great for connecting one useful piece of content to another useful piece of content. But what does that have to do with how you synthesize either piece of useful information?

      • Joshua Wulf 2013/01/09 at 21:53 #

        That is a synthesis of useful information.

        You can automatically synthesize concepts with references in presentation (e.g: link each ingredient in a list of ingredients to a description) – if you have them available as atomic topics.

        Maybe that is the point you are making? Not against anti-analytic, but pro-synthesis?

        useful content is not created by separating these categories but by fusing them together in the correct way.

        Actually, I read over the whole thing again, and I’m with you on this one. I’m looking at my copy of “Mapping Hypertext” as we speak.

        I agree that DITA is lacking a coherent strategy for reassembly. I see DITA and IM as complementary and a good match.

        I would say:

        useful content is not created by separating these categories but by fusing them together in the correct way (after they have been separated).

        • Mark Baker 2013/01/11 at 14:04 #

          Yes, I think we are converging a little here. But let me follow up on what “after they have been separated” means?

          Do you mean that they have to be treated as separate objects for authoring purposes. If so, I would suggest that that is an authoring process discussion that should be orthogonal to the the information design question.

          Or do you mean that they should be separated out from one another in the organization of the document presented to the user? If so, I would suggest:

          a. that this is often true, but not necessarily always true.

          b. that IM’s much richer set of information types might be a finer instrument for this kind of design work than DITA’s troika.

          c. that in practical terms of giving guidance to authors, the types of the blocks are actually much more specific than either DITA or IM presupposes, so that it is useful to tell recipe authors that they should separate the list of ingredient list from the preparation, not, in abstract, that they should separate references from procedures.

  10. Joshua Wulf 2013/01/09 at 21:43 #

    This blog post explains it more detail, and includes a working demo using documentation produced at Red Hat: http://old.atmayogi.com/node/5095

    Is there a difference of opinion here? Perhaps:

    You are unlikely to find another procedure that works with the same ingredient list, or another ingredient list that works with the same procedure. They are two types of information, to be sure, but they are inextricable joined together and of no use when separated. No purpose would be served by separating them at the authoring stage, and no purpose would be served by presenting them separately to the user.

    Atomic descriptions of ingredients (concepts) are useful, because they can be automatically linked, injected, added as pop-ups, etc… into the ingredients list by expert systems.

    As for separating references and tasks, as in the example of a pizza recipe steps and its ingredients, an obvious immediate application is that you can tell an expert system: “only inject concept links into the reference”.

    In another example, I have reused the same task for different product releases, and provided the release-specific parameters as a reference. The task is the same for both releases, but there are some different values that must be used.

    So my conclusion is that there is value in the distinction as well as in the various presentation syntheses that are enabled by making the distinction at authoring time.

    • Mark Baker 2013/01/11 at 14:17 #

      The word “separation” is dangerous here, for reasons noted above.

      Atomic descriptions of ingredients (concepts) are useful, because they can be automatically linked, injected, added as pop-ups, etc… into the ingredients list by expert systems.

      What you need for this is not that the descriptions be separated, but that they be addressable. Store an entire recipe in a single file and use recipe-specific markup to encode it. You can then address the ingredients separately for any of the purposes you mention.

      As for separating references and tasks, as in the example of a pizza recipe steps and its ingredients, an obvious immediate application is that you can tell an expert system: “only inject concept links into the reference”.

      Again, this is an addressablity issue, not a separation issue.

      In another example, I have reused the same task for different product releases, and provided the release-specific parameters as a reference. The task is the same for both releases, but there are some different values that must be used.

      That’s fine, but separating information blocks for reuse is not the issue here. The issue is how do you synthesize them. If you separate them for authoring convenience and then present them separately when it would be better for the user to have the presented together, then the authoring tail is wagging the presentation dog. The point of my post is that separation is not a valid universal design principle for presentation. The authoring issue is entirely orthogonal.

      So my conclusion is that there is value in the distinction as well as in the various presentation syntheses that are enabled by making the distinction at authoring time.

      As long as in making the distinction at authoring time you do not make it a design principle for the information you produce, sure. But many people have taken this idea of separation as being a design principle for the presentation of content, and that is what this post is about.

      On the authoring question, I would say that there are much better approaches — but that too is orthogonal here.

  11. Judy Kessler 2013/01/09 at 22:35 #

    Mark, you wrote:
    “In fact, the recipe really seems like concrete proof that you cannot successfully separate concepts from tasks. Neither the ingredient list alone nor the procedure alone would be of use to anyone. They only work together.”
    True, insofar as this example goes. But the ingredients list isn’t the concept. “Pizza” is a concept that I might read if I’d never eaten it before. Or perhaps a discussion of the differences between thick crust and thin crust pizza, or Chicago versus Boston North End style pizza.
    I might want to read those concepts, but not actually bake a pizza. Conversely, if I want to bake a pizza, I want the ingredients list and the steps, but I don’t want you to tell me what pizza is–I know that already, so don’t waste my time.
    Similarly, I might want just the ingredients for my shopping list, or so that I can get them all ready before I start working–or so that I can easily delegate the shopping to my husband.
    Personally, I find recipes that mingle the ingredients and quantities with the steps, rather than breaking them out at the top, difficult to follow. Even more challenging are recipes that appear to list all the ingredients, but then when you’re halfway through the steps you find some important item or quantity that was left out of the list at the top. And that happens all the time in technical content when you just munge it all together.
    Okay, you get what I’m saying, I hope. Concept/reference/task isn’t just about reuse or productivity. It’s also about considering how a real user–or a group of users in an enterprise–use different sorts of closely related information, at different times, for different reasons.

    • Mark Baker 2013/01/11 at 14:37 #

      Judy, thanks for the reply.

      You can certainly find many cases where a sensible separation of information leaves you with presentation units that are only concepts, or presentation units that are only tasks. That’s fine, as long as you don’t extend it to a universal principle that every unit of presentation must contain only a single concept, as single task, or a single reference.

      And while DITA does not in any way state that as a design goal, it is what many people have apparently taken away from DITA, and it is also the practical effect of applying the DITA standard transform for HTML output, and something we see in many doc sets produced from DITA.

      I trust you understand that I am not in any way advocating that recipes should mix ingredients into the steps. What I am saying is that there is no good reason to present recipes to the reader with the ingredients on one page and the preparation on another.

      Recipes are a well know information structure that everyone recognizes. Anything you do to change it will make it less usable. Even if someone just wants to make a shopping list, they will be best served by being presented the whole recipe because that is the form that they expect the information to be in and that they know how to navigate. Furthermore, the rest of the recipe provides context that might affect their shopping decisions — how long is the prep time, does it need a special pan, etc.

      As I have noted before, tasks are not performed in isolation, the real tech pubs need for most folks is decision support (http://everypageispageone.com/2012/11/05/the-real-docs-need-is-decision-support/), and that requires context.

      If we are talking about some kind of online recipe system where the shopper can choose the recipes they plan to make and have the system generate a shopping list, then the system does need to be able to address the ingredient list for each recipe chosen, and then to be able to consolidate the same ingredient occurring in more than one recipe and add the quantities together.

      As noted above, though, addressability, not separation, is what you need to accomplish this. And by itself, concept/task/reference seaparation will not give you the addressability you need for this kind of operation.

  12. John Tait 2013/02/11 at 10:16 #

    I like these posts. The three DITA topic types have always bothered me because I don’t come from the world of computer documentation, and because itty-bitty topics to click through doesn’t seem a friendly thing to put in front of readers.

    I really like the Hughes Aircraft STOP Report. STOP resembles DITA in that you have a thesis sentence, which is very similar ot DITA’s shortdesc.

    STOP has a different emphasis from DITA in that information typing isn’t considered at all. What STOP “storyboards” do it try to make a clear, coherent argument or point.

    Compare STOP’s witty, rather droll writing with any typical DITA “content” as you’ll see the difference straight away,

    • Mark Baker 2013/02/13 at 13:10 #

      Thanks for the comment, John.

      I don’t know a great deal about STOP, but from what I have very briefly read, it seems like they embody more of what I call the concept of the “narrative minim” than does DITA, and perhaps more than IM as well.

      Can you point to any specific examples of STOP content so we can compare the style?

Trackbacks/Pingbacks

  1. DITA: Similarly Unique/Uniquely Similar | DITA Chicks Blog - 2013/01/16

    […] Mark Baker’s lament on the “terrible troika”: Confusing Analytic and Synthetic Truths in Defining Topic Types at http://everypageispageone.com/2013/01/08/confusing-analytic-and-synthetic-truths-in-defining-topic-t…). […]

  2. Lessons from @raygallon on cognitive #UA design « Kai's Tech Writing Blog - 2013/01/24

    […] One of the most important consequences of Ray’s paradigm for us tech comm’ers is that it effectively abolishes a dear dogma of topic-based authoring, namely the separation of concepts and tasks. Ray explains that just because we need to understand these areas separately (when we make sense of products during analysis) doesn’t mean we need to keep them separate when we present them again to users (during synthesis). Imagine a pizza: You need to understand crust, tomato sauce and toppings separately – but you would never serve them separately to the user. (For more about this, see Mark Baker’s blog post.) […]