Topic Patterns vs. Topic Types

This entry is part 1 of 4 in the series Topic Patterns

One of the principles of Every Page is Page One information design is that an EPPO topic conforms to a type. But I have come to think that that formulation is not quite right. It should really be, an Every Page is Page One topic conforms to a topic pattern.

The difference between type and pattern

What is the difference between a topic type and a topic pattern? In structured writing terms, a topic type, or, more generally, a document type, is a formal set of rules about the structure of a topic which is capable of being expressed by a schema. In most cases, that means an XML schema or something similar. This usage is consistent with the use of the word “type” in other computing applications. A type is a data definition.

Of course, a topic can conform to a type without actually conforming to a schema, or being written in any form that support schema validation. You can write a topic in plain text that follows the prescriptions of an XML schema definition exactly, though you won’t be able to validate it, or use automated publishing tools to format and present it.

To say that such a topic conforms to a type, therefore, is a little confusing. It may conform to the rules of the type, but it is not an instance of the type because it does not have the markup that can be used to identify it and process it as that type.

What it does do, though, is conform to a pattern. Thus we can say that the topic conforms to the pattern, even though it does not conform to the formal type definition.

How types relate to patterns

If that was all there was to the distinction, it would just be a bit of semantic quibbling. But I think there is more, and that it is important.

In the Every Page is Page One book, I use a recipe as an example of a topic type. But in fact a recipe is a more general pattern that different publications may interpret in different ways. The fundamental parts of the recipe topic pattern are universal, but there are variations in how the are arranged and all sorts of optional extra elements, like nutrition information, preparation and cooking time, and wine pairing.

Of course, you can have optional elements in a topic type as well, but formal types are generally more useful — provide more guidance, more error detection capability, and more reliability in different applications — if they have as few variation and optional elements as possible.

Types support business requirements

Any one recipe publisher, for instance, may want to mandate that wine parings be stated for all recipes. That requirement may be an essential part of their identity, their marketing strategy, their revenue stream (through affiliate agreements with wine producers), and their navigation schema.

For such a publisher, the wine pairing information is an essential part of their recipe topic type. Given how important it is to their business, it is probably a complex structure containing several fields whose values are validated against a formal taxonomy of wine terms.

The requirement for that extremely detailed wine pairing section does not hide the fact that the recipes follow the recipe topic pattern. And following that pattern is an important part of the usability and findability of the recipes, since readers who are looking for a recipe, and deciding which dishes to cook, look for content that follows the recipe topic pattern that they know.

It is important, therefore, that this publication’s recipe topic type conform to the general recipe topic pattern, and also that it be an extremely specific type definition that captures the information that is essential to running this publisher’s business.

Elements of a pattern not expressed in the type

But a topic pattern may also be specific in ways in which a particular type that follows that pattern is not. For example, the procedural part of a recipe may look like any other numbered list of steps, and may be modeled that way in most recipe topic types, but there is actually an interesting and important pattern to recipe procedures that is not found in all procedures. We could call it the “meanwhile and let” pattern, as exemplified in a this recipe for Curried Pumpkin and Wild Rice Soup.

Bring a small saucepan of water to a boil. Add the rice, and simmer until tender, 30 to 40 minutes. Strain and let cool.

Meanwhile, combine 2 tablespoons of the raisins and 1 tablespoon of the vinegar in a small bowl. Let sit at room temperature until ready to serve.

“Meanwhile” and “let” introduce an interesting pattern into a recipe procedure. The standard form of a procedure is that each step is completed in turn. The first step is performed to completion, then the next, then the next, like this:

linear-procedure

But in cooking, part of the art of a meal it to make sure that each dish, and each of the parts of a dish, are ready at the same time. Rather than each step ending before the next begins, in many cases the whole point is to make sure that all the steps end at the same time.

This actually creates a complex pattern in which some steps are sequential and some run in parallel. In some cases the parallel steps run all the way to the end of the recipe. In other cases, the thing they produce is used as an ingredient for some later step. Thus the model of a recipe procedure looks something like this:

recipe-procedure

 

Creating a formal content model to represent these relationships could be quite complex, and it is not clear it it would make recipes any easier to write or to follow.

Rather than try to express this elaborate pattern, what recipes actually do is quite simple. When a step is supposed to run in parallel — which almost always means that some part of the dish is cooking while the cook does something else — the following step begins with the word “Meanwhile”, indicating that this step is to be performed while the ingredients of the previous step are cooking.

In the case where the output of one step is going to be required as the input of a later step (not necessarily the next one) this is indicated with  words like “let stand,” “let cool,” or “set aside.”

The elements of a finished dish come together like the converging branches of a tree, and getting that convergence pattern, and its timing, right is vital to the success of a recipe. That tree could be modeled as a formal data structure. In future posts, we will look at examples where it makes very good sense to model a set of inputs as a formal data structure and derive a procedure from them automatically. But that is seldom going to be applicable to the writing of recipes.

Though the “meanwhile” and “let” pattern is part of the rhetorical structure of the recipe topic pattern, and important to how you teach people to write recipes, it is unlikely to be part of any recipe data type.

Data structure vs. rhetorical structure

A topic pattern, then, is a rhetorical structure. A topic type is a data structure. The data structure and the rhetorical structure intersect but the data structure does not usually encompass everything that is in the rhetorical structure, while the data structure may make data requirements that are far more explicit and formal than the rhetorical structure demands.

As we shall see later, the data structure may also depart substantially from the order and form of the rhetorical structure, and abstract out many of the rhetorical elements, so as to automatically construct the desired rhetorical structure from the data in a more efficient and reliable manner than can be done by hand.

This is why I think that the distinction between a topic pattern and a topic type is worth making, and why I should have said not that an EPPO topic conforms to a well defined topic type, but that it conforms to a well defined topic pattern.

Of course, if you are using structured writing techniques to create EPPO topics, you will probably want to create topic types that help ensure that your topics consistently conform to the appropriate topic pattern. But these two ideas are separate, and it is important to keep them separate.

In following posts, I will be looking at a number of different topic patterns, and why they matter for effective communication.

 

Series NavigationSuccessful Patterns are the Best Guide to Information Design >>

, ,

13 Responses to Topic Patterns vs. Topic Types

  1. Jonatan Lundin 2015/01/05 at 15:56 #

    Interesting article. The introduction of topic pattern reminds me about principles in text linguistics. Researchers within text linguistics (a branch of linguistics) deals with texts as communication systems. They are investigating the concept ‘text’ and what makes some set of sentences added after one after each other, one or several coherent text(s).

    A topic pattern as you describe it, seems very similar to the definitions text linguistics make about a text. An EPPO topic could essential be seen as one (1) coherent text. What is interesting is that text linguistics say that there are different types of texts, which has certain characteristics (which to me equals a topic pattern).

    A learnt back in school that a coherent text has a macro theme (makrotema in Swedish – not sure if the translation is correct). The macro theme is what the text is about “Aboutness”. A recipe is about a certain dish. Then we can say something about a theme, the proposition. A text can say how to make the dish.

    Then, a coherent text may have micro themes and micro propositions (as well as implicit and explicit themes and propositions). A theme makes the “rema” in a following sentence, and thus we establish bindings.

    Well, text linguistics has provided so many more definitions and principles which are invaluable for a technical writer when crafting a coherent text, such as intentionality, acceptability, informativity, situationality, intertextuality etc.

    Since text linguistics has struggled for many decades to define the characteristics of a coherent text, you could probably use some or all of these definitions when defining the concept topic pattern.

    What is interesting (to me at least 😉 is that text linguistics try to analyze an already written text (a tradition that goes a long way back to hermeneutics and text interpretation), but what we are talking about is the structured rules and principles for how to write a text.

    So it would be interesting to see how we could use the knowledge provided by text linguistics when defining topic patterns (or text types). We need such definitions. How many ‘texts’ do end users need? Why and when? I personally believe that for example the three DITA topic types are far too broad and generic and do not reveal the real need of users.

    As you know, I depart from another perspective. The searching user is asking questions and thus we can (or must first) define types of questions. An answer is a coherent text – or topic if you like. We may very well say that an answer to a certain type of questions shall follow a certain pattern.

    This perspective means that we do not put a strong focus on first trying to establish types of text pattern. Which to me becomes a bit awkward if we do it before understanding the user behavior (what information do they need, when and why and how to the express that need).

  2. Mark Baker 2015/01/05 at 16:44 #

    Thanks for the comment, Jonatan,

    You bring up an interesting connection. Certainly the idea of “aboutness” is important for defining good topics. The EPPO principles of a topic being self-contained and having a specific and limited purpose are really about it having “aboutness”. If a topic does not have clear aboutness, it will not be a good topic.

    The is also an important distinction to be made between what a topic is about (its subject/macro theme) and the things it talks about (its subject affinities/micro themes). An omelette recipe is “about” cooking omelettes; it “talks about” eggs and pans and spatulas. It is not the place you go to learn about eggs or pans or spatulas, but if you read it you may need additional information about those subjects.

    In SPFE, links are formed automatically based on index entries that state what topics is “about” and semantic annotations that state what topics “talk about”. This is how it implements the EPPO principle of linking richly along lines of subject affinity.

    I agree with you about the DITA topic types. Indeed, I don’t think they were ever intended to express aboutness. They were intended to distinguish different kinds of information. And while the distinctions they make are real, it is not obvious to me what purpose is served by separating them out in the way DITA does. Aboutness may require different types of information, as a recipe, for instance does. And the pattern that established the aboutness of a recipe is far more specific than merely one concept (intro), one reference (an ingredient list) and one task (preparation steps).

    In other words, if someone asks, “How do I write a recipe”, the answer, “one concept, one reference, one task,” is a wholly inadequate answer. It tells you nothing about the recipe topic pattern and does nothing to establish the aboutness of a recipe.

    Where I would part company from your analysis is when you say “an answer is a coherent text”. Attractive as that vision is, it works only in the simplest of cases. As John Carroll showed, readers are infinitely varied in their backgrounds and their aims and are burdened with the paradox of sensemaking. And as we also know, readers seldom form their questions fully and accurately, even in their own minds. We cannot write topics that reliably, and by themselves, answer all user’s questions.

    What we can do is to create an rich information field in which users can find their way to the answers they need through a wayfaring process that has as much to do with the reader figuring out what their real question as it does with them finding the answer. (See: http://everypageispageone.com/2014/05/26/design-for-wayfinding/)

    Thus topic patterns have more to do with establishing a consistent, reliable, and comprehensive information field in which the reader is free to move and explore.

    Thus part of the recipe topic pattern is that it is written for an experience cook and does not attempt to teach basic cooking terms and techniques. This is not because the writer is certain that only experienced cooks will ever read or attempt the recipe, but because they know that there are other resources available that teach basic cooking techniques — which have topic patterns of their own. Including those techniques inline in every recipe would violate its topic pattern and compromise its aboutness, making it less useful to most of its readers.

    • Jonatan Lundin 2015/01/07 at 04:14 #

      We have concluded before that we have somewhat different viewpoints regarding the starting point for technical communicators when identifying what to write. But, our view is the same regarding user behavior, which is something as follows:

      An individual attempts to do something, thus s/he has a goal to for example solve a business problem. The user interacts with technology, having a certain goal in mind, as depicted by minimalism. The user is trying to make sense using existing assimilated knowledge, where the user is in a state of confusion, exploration and discovery.

      If existing knowledge and prior experience is not providing support, the individual perceives a problem (a user often has at first a vague idea of the problem) which triggers a need for information. S/he starts to search for information as support to the action of reaching the imagined goal of interaction.

      The user formulates the information need as a set of questions. But, information science has shown that individuals are often bad at expressing an information need. Often they do not know what to ask for and only knows it when they see it (since recognition outperforms recall).

      When users search, they start somewhere, selecting a preferred information source – the manual, website filtered out by Google etc. They display a seeking behavior you call “way finding”, which information scientists have denoted “berry picking” or “evolving search”.

      I agree that end user assistance shall not be designed as a static book; rather an information field of interlinked articles (something I have touched upon here: http://excosoft.com/can-tech-writers-create-links-without-even-writing/). But, I say that it is necessary to understand the information needs of users, thus the “true” questions they ask, before attempting to design such information field.

      But, I’m not saying that we should solely rely on the explicit queries that users express, as a foundation to know what to write. This, since these expressions are not “trustworthy” (as mentioned above). But, we could get to know this need by in depth analyze the conversation that happens between users on the web.

      But for a technical communicator, working in parallel to product development, this conversation is not yet available. We need additional mechanisms to understand the information needs of individuals.

      My research is in part contributing with knowledge on how this can be done. I am using various theories and methodologies, such as activity theory and participant observation, as a foundation to describe what users need. (BTW; interviewing users as a method to describe information needs is not reliable, since what people say they need often differs from what they actually need).

      I’ve made an attempt to shed some light on an approach of using activity theory to describe what information users need (and thus what type of questions they ask – See for example http://excosoft.com/types-questions-users-ask/).

      My assumption is that there are information needs that are common across users (having the same goal) of a product, which are there to be found. Having this said, I also acknowledge that there are information needs that are specific to a certain individual, and thus cannot be predicted. I do not know what the ratio is between “global/local”.

      But, I am afraid that we may end up creating an information field that becomes useless, if we do not in depth try to understand what individuals need and demand. The contrast to the “individual” perspective is an epistemological perspective, where a community of experts (often technical communicators) decides what information someone needs to solve a problem.

      So, I argue that understanding users is crucial not only to know what EPPO topics to write, but also to know what information, according to what pattern, to include in each. But, should an EPPO topic be designed to answer one (1) or several questions? If several, which ones are to be “bundled (and why – why not link each answer)”?

      If we know that certain types of questions are always asked in a certain order, a topic pattern could be answer those questions in a certain order. I guess that you do not take a stand on such design questions, rather it is up to the information designer to decide how to organize topics.

      • Mark Baker 2015/01/07 at 09:06 #

        Hi Jonatan,

        Yes, I think we agree on the things you say we agree on.

        Here perhaps is where we may differ (though then again, it may simply be where we express ourselves differently):

        Users turn to documentation (or, to be more precise, they search for content and/or experts) when they are unable to complete a task. But they don’t search for the information they need. They search for how to do the task. (Spend some time on StackOverflow and this pattern is abundantly clear.)

        Why? Because they do not know what information they are lacking to complete the task. At least, the class of users that we can describe (per John Carroll) as “learners” do not know what they need to know to complete the task. This is where their cognitive gap manifests itself. If they understood the tool and the task thoroughly, they would know what they information they needed to complete it. The problem is they don’t know what they need to know, and therefore can’t ask for it.

        There are, of course, users who are not learners, who understand the tool and the task perfectly, but need certain data points to complete the task. They do ask for information, but their needs are easily met by a well organized reference, so there is no mystery about how to serve their needs.

        Also, there are some people who think they know what information they need and are wrong. They will ask the wrong question. You see these on StackOverflow as well. People respond to them by asking what they are trying to do. In other words, they are prompted to rephrase their question as a how do I do this task question.

        It is pretty difficult to create content for the person who is asking the wrong question (except in a forum like StackOverflow, where you can address them directly), so we are not really going to be of much help to them until they figure out that they are asking the wrong question, as which point they will start asking how to do the task.

        Which means that the users we can help are the learners who are asking how to do a task.

        It is our job to know what information people need to know in order to perform a task. This information is not obtained by studying people, but by studying the task.

        Thus I would contend that the first business of a technical writer is not understanding users but understanding tasks.

        Of course, not all users are alike, and the differences certainly affect information design. But the differences are not in information needs. Everyone who attempts to perform a task needs to know what anyone needs to know to perform that task. They don’t differ in what they need to know. If they differ, it is in what they don’t know.

        The problem is that tasks are build out of simpler tasks. To make an omelette, you need to break eggs. So the question becomes, in order to write an omelette recipe, do I have to tell people how to break eggs?

        And the answer, of course, is no. Recipes do not teach basic cooking techniques. This is a well established part of the recipe topic pattern.

        The information design problem is:

        • What information do I include?
        • What background information do I include inline?

        The first item is answered by looking at the task.
        The second answer depends on the users. There are a number of ways to get this information. One is to study users. Another, and I think a cheaper and more reliable one, is to study topic patterns.

        It is easy to forget that the marketplace is the biggest and best usability lab in the world. The market discerns what works and what doesn’t and brings what works to the fore. Patterns that are successful in the market are likely to continue to be successful in the market.

        Studying successful patterns is, therefore, a way of studying users. The patterns are formed by the action of users selecting things that work for them and rejecting things that don’t.

        From an academic point of view this study may be unsatisfying, because it does not tell us why the pattern succeeded. But from a commercial point of view, it is highly practical, and highly reliable.

        What the Web has done, both for products and for information, is to vastly accelerate the discernment process of the market. The market now determines which patterns work and which don’t far faster than it ever did before.

        This means that other approaches to discerning user needs are at an increasing disadvantage. They take too long. They began as an attempt to predict what the market would do, but now the market yields the information faster than the experiments that try to predict it. Thus we see the rise of the “minimal viable product” approach in the Lean startup movement.

        Also, the market can test things that are just too big to fit in the lab. Usability studies of content isolate the content from the context of the Web. But that falsifies how content is actually used. Better to simply publish the content and measure how it performs.

        This is why I think the study of successful topic patterns is the best way to answer many information design problems today.

      • Mark Baker 2015/01/07 at 09:08 #

        Oh, and thank you very much for prompting me to articulate the above, which will probably find its way into another post in this series.

        • Jonatan Lundin 2015/01/08 at 05:23 #

          Yes, thanks for the discussion. It makes you reflect on your thoughts, which is always a good thing. Especially when starting a new year (BTW: I hope you get a happy one).

          But I disagree to some of the claims you make. You say that “users don’t search for the information they need. They search for how to do the task”. This I believe is not the case. Information science has proven for a long time that information needs and uncertainty is the main driver for people to search for information.

          A certain information need can be to know how to do a task, but a tentative result of my research says that individuals (at least the one I study) very seldom need information on how to do a task as an explicit step-by-step advice.

          Instead, users set up goals on what they want to do. They form a strategy on how they believe this goal is reached and they act. When the reality does not match the strategy, they perceive a need for information (sometimes they give up or ignore the problem).

          What they often search for is not the complete strategy on how to reach the goal (the whole task) but small fractions of information that is missing to support their imagined task strategy, such as “Where is the print icon located?”, “Is it possible to export a file that contains xx?” “What does ABC mean?”.

          Users don’t want to abandon their task strategy; what they believe is right. They may even search for evidence on their own explanation as I depict here: http://excosoft.com/users-read-topics-think/.

          But, I agree that users may ask wrong questions. That is why it is not meaningful to rely an information design solely on the explicit expressions user make when searching. What I propose is that the type of questions users state cannot be invalid, but sometimes the subjects they express can be invalid.

          As when a users asks “Is it possible to export to XML?”. To ask if something is possible is valid, but it is invalid to ask if the product support “export to XML” since this is not possible.

          So we need to understand the type of questions users ask and then craft answers containing the valid subjects. This, cannot be done by solely focusing on tasks, but on the users themselves and the goals they set out to pursue.

          But I agree that a rich interlinked information field is a fruitful way to help users find the valid answers. If a user starts off by wanting to find out if it is possible to “export to XML”, s/he will find content and follow links to eventually end up knowing that is it not possible.

          Another way is to build a search interface that mimics a human dialog (as I depict here: http://excosoft.com/will-answer-easy-find-mimic-human-dialog-user-assistance/). The user can ask for all answers that depict “what is possible” and then explore that field. Thus “Learning-by-searching” which means that the mental model of the user is corrected as the user searches.

          When you say that “the first business of a technical writer is not understanding users but understanding tasks”, you exemplify the epistemological view, where the expert dictates what information users need and shall read.

          To force the user to find information about where the “print icon” is located from a page that describes how to do a task, I believe is not going to work.

          • Mark Baker 2015/01/08 at 06:48 #

            Well, yes, the expert is the one who knows what you need to know to accomplish a goal. If the user needs to know how to export to XML, then your first business is to know how to export to XML. You are not going to be any use to them unless you know how to do that.

            And the way that you know that some users are going to want to export to XML is that your product can export to XML. (There may be off-label uses of your product that involve extracting XML from it for purposes your company did not intend or envision, but, by definition, you do not document off-label uses, at least until your company decides to bless them and make them on-label.)

            The problem with experts, of course, is that they suffer from the curse of knowledge. They often don’t realize that the things they know are specialized knowledge that other’s don’t know. Therefore they answer questions in a way that assumes their audience knows things they don’t.

            So the second responsibility of the writer is to figure out what needs to be said to the audience and what does not.

            One way to figure this out is to go and study users. But this is a very expensive way to do it. It also requires a lot of specialized training in experimental design that most subject matter experts and most writers do not have. (Indeed, studies seem to indicate that many professional scientists don’t have it either, since a large proportion of published experiments cannot be reproduced.)

            Another way is to emulate patterns that have been successful in the past. When someone invents a new dish and decides to publish a description of it, they do not start by doing new research on people who want to cook. They follow the well established recipe topic pattern.

            Topic patterns arise out of a natural selection process in the marketplace of ideas. The explanations of things that are most successful with readers get read more, distributed more, and emulated more. Over time, a successful pattern emerges and is refined. This actually constitutes a broad based, perhaps multigenerational user study — something far more comprehensive than anything you could design in the lab.

            This does not mean that following a topic pattern is easy. The patterns themselves have to be studied and understood. They are not, therefore, a paint by numbers system. But they are an enormously valuable source of the kind of user information that you need to communicate effectively.

            My beef with a lot of current tech comm practice is that it is emulating outdated patterns from the age of paper. The age of the web has established a new set of patterns, and user’s information seeking behavior is not tuned much more to those patterns rather than to the paper-age patterns.

            In my reply above I tried to make a distinction between learners and what I will now call “data seekers”. (The fact that I did not give the second group a name is clearly a problem, and probably violates a topic pattern for making distinctions between two groups.)

            Data seekers look for individual pieces of data, like “where is the print icon”. Learners ask how to do things. The distinction is by no means always clear in the language. “How do I export to XML” could be either. It sometimes takes some conversation to discover whether the person who asks this question is looking for a data point (where is the “Export to XML button”) or a task (“transform the data into XML that conforms with a particular schema”). This is why conversations on StackOverflow so often involve asking the original poster to clarify what they are trying to accomplish.

            I’m not clear, though, on the distinction you seem to be making between “task” and “goal”. I don’t use “task” to mean “explicit step-by-step advice” (DITA seems to be teaching us to say “task” when we mean “procedure”). I use it to mean the thing the user is trying to accomplish, which is pretty close to being a synonym for goal. People search for their goal.

            And I agree that people often do not search for their final goal, but for what they guess (often incorrectly) are the subgoals leading towards that goal. They guess at solutions and ask how to execute them.

            When people ask the right questions using the right terms, there is little difficulty in guiding them to the information they need. In fact, today, Google will generally take them there instantly. The main concern in providing information to these users is to make sure the information is complete and consistent. Good references are the foundation of good tech comm.

            But only experts search like this. The rest are stumbling. Can we find useful patterns in their stumbling that will change how we design information for the better? Certainly studying the keywords they use can help us with SEO. Beyond that I am unconvinced, particularly as a strategy for working writers with a deadline. I think there is far more practical value in studying successful topic patterns.

            Of course, it is always possible that there are better topic patterns out there that might be discovered by research of the kind you are doing. John Carroll’s research certainly taught us a lot and arguably led to the development of new topic patterns. Then again, I think we could also argue the the open colloquium of the Web has produced an information field that is very much like what Carroll described. Carroll’s real contribution may be to explain why these patterns work, and to legitimize their use, rather than being the origin of them.

            There is among writers a huge reluctance to follow some of the patterns that have emerged on the Web, despite their evident success. Perhaps they feel that they are not “correct” in some way. Certainly there is widespread feeling that web content is largely bad, despite how widely it is used. Certainly there is a lack of appreciation of how the Web works as a filter to surfact the most successful content. Sometimes the challenge is not to discover the patterns that work, but to legitimize them so that writers will actually use them.

            If your research can contribute to legitimizing the patterns that work, therefore, it will perform a very useful service to tech comm. For my part, though, I intend to continue studying the patterns themselves.

  3. Jonatan Lundin 2015/01/09 at 04:12 #

    Thanks for clarifying your view. I make much more sense now as you clarified that with “task” you denote the same thing as I do using “goal”. The discussion we are having is important from many perspectives, so I would just like to summarize some key points.

    We both believe that users search for information when they are unable to complete a goal/task they have when for example using technology (as use “goal” below). Both the expert but especially the novice learner may express invalid queries, ask the wrong questions, and learn as they explore an information field (which they do to find what they are looking for).

    The EPPO design approach is based on a view that learners in general are stumbling and most often search for information on how to reach this goal. You say that experts in general search for individual pieces of data, such as where something is located, which often is on a more detailed level than how to reach the entire goal (but related to the goal).

    Then, an EPPO page shall include all the information that an individual must know (assuming a certain knowledge level) to reach a particular goal. Thus, both the expert and the learner can find information from this single page, which is “about” the goal.

    You say that knowing about the goals is fundamental, as they directly impacts the number of EPPO pages a writer needs to design. It is the job of a technical writer to know what information people need to know in order to perform a goal. This information is not obtained by studying people, but by studying the goals. The information people need to know is organized according to a certain topic pattern.

    To identify the goals individuals set out to perform, can be investigated in many ways. To analyze the conversation on the web is one way, to analyze users another.

    I personally believe that categorizing users into groups is a dangerous thing when you design information for a user who has a goal of making the product complete what it was designed to do (http://excosoft.com/technical-communicators-avoid-target-group-analysis/).

    But, I believe that it is too broad to assume that individuals, and especially experts, most often search for information on how to reach their entire work task related goal. Many individual, including learners, have often the capability to form an idea on how to perform the work task goal (we believe in something – and we stick to it, which is tried and explored, as user behavior in minimalism thought us).

    When stuck, they form another goal (a sub goal denoted information-seeking goal), which is to find certain type of information. Thus, they lack and perceive to need for information to be able to reach the work task goal. When formulating this information-seeking goal, they must reflect on what they lack.

    When doing this, humans try to understand what it is that makes the world not work as we want; so we formulate explanations, hypotheses etc. I assume that individuals many times seek for information needed to confirm a believed explanation to why a product is not working as the user wants, how to do something etc.

    This information-seeking goal becomes expressed as one or many questions, which is then most often not a high level questions such as “What do I need to do to reach my goal X?”. But again, high level or not, depends on level of experience, cognitive style, how new the product is on the market (paradigm), motivation, risk-taking behavior etc.

    It all boils down to that you believe that technical communicators must analyze the goals individuals set out to perform and design an EPPO page for each goal, to include all knowledge they need to perform it (minus what they already know). I think this is a very good step in the right direction.

    I also believe that goals a very central, but instead of ending the analysis when we know the goals, we need to step one level down and understand the type of questions users ask when they try reach a goal. I believe there are a generic set of type of questions users ask, when trying to reach a goal. And, a user may ask many different types of questions to reach a goal. Here, I assume that it is possible to define question types that are generic in the sense that they are not product or user specific.

    But, again, these types of questions cannot be analyzed solely from only looking at the queries people state (since they often does not make sense). We need to make a deeper analysis to find the “true” questions. This implies that the information needs of individuals are in center. I’ve made an attempt to describe such an attempt here: http://excosoft.com/types-questions-users-ask/

    One objective of user assistance is (could be or should be) to help the user transform the stumbling attempts to ask something, to a valid question. The user might ask “I have a problem and need some information”. The user assistance (or the user himself by exploring the information field) must assess the situation and say “Are you asking where the print icon is located?”. The user says “yes, I should have asked that if I knew what it was called”. More info here: http://excosoft.com/will-answer-easy-find-mimic-human-dialog-user-assistance/

    So instead of packaging all answers (all knowledge a user must know) to reach a goal into one single EPPO page, I advocate to treat each answer as a single page and each answer is richly interlinked, to provide a infrastructure to find answers to follow up questions (http://excosoft.com/can-tech-writers-create-links-without-even-writing/).

    • Mark Baker 2015/01/09 at 09:51 #

      “The EPPO design approach is based on a view that learners in general are stumbling and most often search for information on how to reach this goal.”

      Not entirely, no. The EPPO design approach is based on generalizing from successful patterns. Information foraging theory and the paradox of sensemaking help to make sense of why these patterns are successful, when a purely logical approach to information design might suggest something different.

      My main interest in these theories, though, is not as a principle to draw design conclusions from, but as a response those who believe that there is an ideal form of content organization just waiting to be found, since the pursuit of this ideal form tends to make content worse overall, rather than better.

      If I interpret you correctly, you are attempting to understand the psychology of learning and to derive an information design from that psychology. I think perhaps you are attempting to understand my work in the same way. But that is not what I am doing.

      I am looking at patterns that work in the most free and competitive information marketplace the world has known. The kinds of information design patterns that have emerged in this market are often at odds with both traditional information design and psychologically-based predictions of what ought to work.

      For professionals, who need for their material to prosper in this market, therefore, it is important to understand and emulate these successful patterns, because the market has no tolerance for material that does not.

      A very common reaction among professional writers is to condemn the information patterns of the web because they don’t follow either convention or the predictions of psychology. Thus we have books like The Shallows and countless anti-web rants from writers on (irony alert) web forums and mailing lists.

      If we can find insights in psychology to explain why these patterns work, then, I will cite them to encourage use of the patterns. But if psychology cannot explain a pattern that the market produces, that means the psychology is wrong and I follow the market, not the psychology. So if you are looking to understand the psychological basis for the EPPO design pattern, you won’t learn it from me. I follow the market.

      “Then, an EPPO page shall include all the information that an individual must know (assuming a certain knowledge level) to reach a particular goal. Thus, both the expert and the learner can find information from this single page, which is “about” the goal.”

      If we assume a certain level of knowledge, then the topic is written for a user with that level of knowledge, not for both the expert and the learner. Recipes are written for cooks, not for people learning to cook. People learning to cook do use recipes, but supplement them with reference to mentors or other material that covers the basics of cooking.

      I think we can draw some generalities about the how successful topics are addressed to populations of users, and my EPPO principles attempt to define them in general terms. But again, this is based on an observation of patterns that work, not on a theory of learning.

      For this reason, I think it is important to study actual topic patterns that work, rather than merely stating rules and expecting to always derive correct information designs from such rules.

      “So instead of packaging all answers (all knowledge a user must know) to reach a goal into one single EPPO page, I advocate to treat each answer as a single page”

      EPPO does not advocate all knowledge a user must know to reach a goal on a single EPPO page. In fact, that is the very thing that EPPO rejects. EPPO says that a page should have a specific and limited purpose, but that the purpose of the page is not synonymous with the purpose of the individual reader. Content is written for a population of readers, not for individual readers. It is, in other words, like a bus service, not like a taxi service. The purpose of an EPPO topic is to be an efficient node of an information network traversed by many readers with differing goals. It is sized for that purpose, not the purpose of one individual user.

      While I said that what I mean by task is nearer to what you mean by goal than it is to a procedure, I think there is still a significant difference. You see “goal” (I think) in psychological terms. I see “task” in terms of a job of work done. The reductio ad absurdum of “treat each answer as a single page” is a page whose only content is “42”. Discovering that the value of a particular setting is 42 may be a short term goal, but it is not a task. Tasks require data as input, but one data point is not a task.

      One of the key ways in which EPPO addresses the how big is a topic question is by not having one rule of thumb for it, but seven. The seven principles of EPPO, taken together, provide guidance for sizing content. One of those principle is that an EPPO topic conforms to a definite pattern. (This principle is based on observation of successful content, not on psychological theory.)

      I don’t claim to fully comprehend the psychology of this, but I think it is very clear that when content is cut too small, it becomes shapeless and when it is bulked up too large, it also becomes shapeless, and that shapeless content does not work.

      The correct size, therefore, is not one task or one goal or one question, but a unit that has a clear and definite shape. A content unit is the right size, therefore, when it has a definite pattern.

      Thus again, the study of patterns is key.

  4. Carl Lemp 2015/01/14 at 09:59 #

    While it is not the main subject of your post, you touch on the topic of sequential versus parallel steps. The “Meanwhile” and “let” rhetorical pattern is a very loose structure that identifies parallel steps but it does not provide much in the way of guidance for the timing and precise interconnection of those steps. In the case of of recipes, that is one reason a novice cook and an experienced cook can follow the same recipe and get completely different results.

    In more technical processes where Standard Operating Procedures (SOPs) are required, the difference can be more profound than a dish which doesn’t taste like you expected it to. Are you aware of any common and effective patterns or types that are used to define the sequential/parallel interconnection of steps more precisely?

  5. Mark Baker 2015/01/14 at 11:03 #

    Thanks for the comment, Carl

    I’m sure you are right that there are cases that would seem to call for a far more rigorous approach to parallel procedures. I would love to see examples of SOP’s that implement this pattern. It is something I will be on the lookout for. (And if any readers can think of examples of this or any other interesting topic pattern, please let me know.)

    Your point about how timing contributes to the relative success of novice and expert cooks is an important one as well. I don’t think there is any doubt that if novice cooks could time things better, they would get better results, or that becoming a better cook has a great deal to do with developing better timing.

    The interesting question is, would a something like a gantt chart, that showed the parallel steps and the timing in precise terms helps the novice cook?

    Carroll’s paradox of sense making suggests that in fact ultra-precise instructions don’t help the novice, who has trouble making sense of them. To use a gantt chart effectively, you have to learn to read a gantt chart. And to understand the process of cooking (or anything else), you have to actually try and fail a few times.

    It also raises the question of whether the recipe topic pattern has reached its optimal form. Clearly it is not perfect at enabling novice cooks to create perfect dishes the first time out, but it seems pretty clear that that is not achievable.

    All sorts of things can inhibit a product or pattern from reaching its optimal form. The network effect can lock out competing forms, while tradition and the need for backward compatibility, and compatibility with existing skill sets can inhibit further progress. The fact that I am typing this on the definitely non-optimal QWERTY keyboard layout is sufficient evidence that all sorts of things can fail to reach their technical optimum.

    We could, of course, argue, that while QWERTY is not a technical optimum, it is a social optimum. That is, given all the social and economic forces that impact the design of things, it is the optimum for this society, even if an independent society might develop a different social optimum.

    But there is reason to think that the recipe topic pattern may indeed be at its technical optimum (which does not mean that every example is optimal, of course). There form is simple and highly malleable, and there is no single vested interest protecting the format. The barriers to entry of a new recipe topic pattern do not seem overwhelmingly high, and the Web provides an easy medium for a better pattern to spread. The needs of new cooks provide an obvious reason to try to improve the form, but still the form remains stable. This is probably as good as it gets for recipes.

    And if so, this confirms that there is indeed a limit to how effective content can be by itself in educating and enabling action. This suggests that a pragmatic study of patterns that work is probably one of the most fruitful things we can do to improve our content.

    Of course, SOPs are a different kind of thing. Novices are seldom let loose on the machinery with an SOP and no supervision, training, or apprenticeship. Rather, they are part of a larger production system which involves training, supervision, and certification. (See: http://everypageispageone.com/2014/06/30/docs-that-are-part-of-larger-systems/) Their function is more to codify acceptable practice than it is to teach the uninitiated. In this sense, the use of highly structured formats that have to be consciously learned, and which might stump the novice, may be entirely appropriate.

    These are important topic patterns as well, but patterns with a different purpose intended for use in a different environment.

  6. Carl Lemp 2015/01/14 at 15:09 #

    Thanks for the link to your previous post. I was not familiar with Carroll’s paradox but I certainly see it in action in the Pharmaceutical industry where I work and where there are SOPs for everything. Unfortunately, the statement
    “When people’s existing mental model of a task does not match the model of the product they are using, they don’t trust or understand what the systematic instructions are telling them.”
    applies in more cases than it should. The minimalist approach helps somewhat but still, one of the difficulties is getting across the order of steps when some are parallel or can be parallel. Since cooking recipes are understood by most people, I was hoping there was some known technique that is a little more precise than “Meanwhile”/”Let” that might be applied SOPs or built into a topic type.

  7. Chuck Martin 2015/03/23 at 21:38 #

    The post and this series have been awesome reading, but I have one quibble with it, and it’s right in the title. While much of the content I’ve developed over the years has been part of a system demarcated by topics, not all of it has. So instead of “topic” types and “topic” patterns, I tend to think more in “content” types and “content” patterns, especially because whenever possible, I prefer developing content that can be used in multiple places. Thinking in patterns at the content level helps us better design content that can be reused.

    For example, one of my first tasks at the new job I started a year ago was to look at a web application’s UI text. Not only did I find a lot of repetition, which I was able to eliminate, I also found the same things said in different ways. By establishing content patterns of even two-word phrases, I was able to make the communication within the application more consistent. It also made writing help easier because the UI content was clearer, more consistent, and communicated use better.

    A good friend of mine, Dave Gash, presented at a WritersUA conference recently a programmatic way to extract blocks of content from the web pages of an online help system and show them as contextual help within a web application’s user interface, essentially as field-level help. Because they are going to be used in a similar way, those chunks of content should probably have a similar content pattern, even though they are also part of a larger topic.

    Not only is it better for content consumers to find topics of the same type of content with the same patterns, the content chunks within the topic are better when they have similar patterns for similar content types. Even when you think of topic types, many topics have content of different types. Task topics could have bits of conceptual, reference, or example content types. Reference topics could have warning or conceptual content types. By thinking of building patterns in our content, we get a significant amount of patterns in our topics for free. Thinking about and creating patterns at the content level helps our content be more scannable, more findable, and more usable.