07 August 2009

Example: Topic Breakdown Using the "Information Causes Change" Heuristic

Since I obviously failed in communicating as clearly as I might have wished to do with the topic general case, I'm going to attempt an example.

It's Recipes Again

Consider Henri-Phillipe, a professional pastry chef, wishing to effectively communicate a recipe for Chocolate Nemesis.
Chocolate Nemesis is a flourless chocolate cake; it's very simple (five ingredients counting the water) but the process of making it has some non-obvious failure modes.
One possible audience for Henri-Phillipe's recipe can be represented by a persona called Aimée, another professional chef although not specifically a pastry chef.
Another possible audience for the recipe can be represented by a persona called Eustace, who cooks a bit and doesn't normally bake, but who thinks a home-made dessert is going to be rather more impressive than anything purchased, and is interested in impressing dinner guests.
So in thinking about how to write the recipe, first you have to decide who—which persona—you are addressing, and what the scenario is. "Enable series production under the supervision of a professional chef in a restaurant kitchen" is a different scenario than "inexperienced baker needs a one-time successful result that can be served to guests".
The scenario is important because the topic-defining single change you are identifying exists on the scale of the scenario. It can't be inferred strictly from the task; you have to know who is doing this, and to what end.

The Specific Recipe

The ingredients for the Chocolate Nemesis recipe are:
  • 675g bitter-sweet chocolate, broken into small pieces
  • 10 whole eggs
  • 575g sugar
  • 450g unsalted butter
The steps in the Chocolate Nemesis recipe are:
  1. preheat oven to 325 F
  2. line two 2" deep, 12" diameter cake pans with greaseproof paper and then grease and flour them
  1. Beat the eggs with 1/3 of the sugar until the volume quadruples
  2. Heat the remaining sugar in a small pan with 250 mL water until the sugar has completely dissolved to a syrup
  3. Place the chocolate and butter in the hot syrup and stir to combine until the chocolate melts and the mixture is smooth. Remove from heat and cool slightly.
  4. Add the warm chocolate mixture to the eggs and continue to beat, more gently, until completely combined (no more than 20s).
  5. Pour into the cake tin and place in a bain-marie of hot water. It is essential for the cake to cook evenly that the water comes up to the rim of the tin.
  6. bake for 30 minutes or until set. Leave to cool in the tin before turning out.
Postreq: When you are ready to serve... (instructions for getting the cake out of the tin)

Conversion to Topics: The "Before You Start" Stuff

I'm not going to go through all or even most of this, but let's look at some of the steps.
The pre-requisites section (DITA task topics may have pre-requisites, context, steps, post-requisites, results, and example elements as section-level components) involves knowing what the oven is and how to properly prepare a cake pan.
If you don't know how to pre-heat an oven, you have no business trying to make flourless cake; this doesn't affect success for either scenario in the same way that we can assume anyone trying to follow either scenario can measure ingredients. (If we were writing a whole "Baking for Those As Can't Tell Eggs from Golf Balls" information set, we'd need a bunch of topics on measuring, conventional terms, and so on.)
Eustace doesn't know how to prepare a cake pan. Aimée (almost) certainly does. (The Aimée I got the recipe from certainly does.) Preparing cake pans is moreover generic; it's pretty much the same thing for any cake where you are going to use greaseproof paper in the pan. So "Prepare A Cake Pan With Greaseproof Paper" becomes its own topic (a task topic), and is referenced in the pre-requisites of the main recipe task topic.

Conversion to Topics: Beating Eggs

Aimée can just do step one as given.
Eustace... cannot. If you beat 10 eggs with sugar until the volume quadruples, you've got something close to 3.5 litres of frothy egg. Once you've added the chocolate mixture, you're going to want a 10 litre bowl to avoid step 4 getting chocolate on the wall. Eustace probably doesn't own a 10 litre mixing bowl.
Eustace also doesn't know that it takes about 10 minutes with an electric mixer on high to get the eggs to the sudden colour transition from orangey-yellow to lemon-yellow that indicates you've converted all the proteins and the resulting egg/sugar froth will stay frothy.
If Eustance doesn't know either of these things, his scenario ("serve to dinner guests") will fail.
"Beat whole eggs with sugar" is a generic cooking task; it gets to be a generic task topic, too, and cross-referenced from the recipe. If we were doing that complete introductory baking infoset, we'd have a bunch of these; beating whole eggs with sugar, beating whole eggs for cake, beating whole eggs for omelets, beating egg whites with sugar, and so on.
"10 whole eggs is a lot!" is specific to this recipe; it's context. The bowl has to be large enough for all of the ingredients in the recipe, much as the butter has to be unsalted, and all the other elements of "enough context to understand the information that causes change".

There's More Than One Way To Structure It

How you structure the topics to meet either scenario comes down to a choice; there's the "one main recipe task topic with cross-references to generic information" approach, and there's the "each step gets broken out as a task for Eustance, using the <related-links/> element to move through them, and there's a single task for Aimée, who needs a lot less explained."
I prefer the first approach; it does no harm if Aimée is able to look up the generic steps easily (maybe she's mostly been making seafood dishes for the last six months, and wants a quick reminder), and this is a recipe; it should support multiple information traversals that get shorter as the cook becomes more familiar with the dish through having made it several times. Industrial process instructions should not do that; they should be structured so that no potentially critical information is ever optional or easily skipped.

Actual DITA

Taking the first approach in DITA, the first task step comes out as:
<cmd>Beat the eggs with 1/3 of the sugar until the volume quadruples.</cmd>
<info>Instructions for beating whole eggs with sugar can be found in
<xref href="GenericBeatingWholeEggsWSugarTopic.xml"/>
<note type="warning">10 eggs will give you at least 3.5 L of sugar/egg froth.
With the additional ingredients, you will need a 10 L bowl.</note>

Some Notes On Context

Context is about the environment for the actions of the persona in the current scenario. So Eustace or Aimée should be beating the eggs and sugar together in a large bowl; the large bowl is context. Beating eggs and sugar together is a direct action, and isn't context, and needs to be considered under the "will this cause change?" heuristic to identify all the changes that might need a topic to address them. That identification has to take into account the persona; Aimée has a large amount of existing knowledge, and consequently fewer things that might cause change, than Eustace does.
Context is always a consequence of the scenario; in the recipe example, it helps to consider questions like:
  • Would Henri-Phillipe tell them to do something different than what you're afraid they might do, were he watching the persona in question carry out these instructions?
  • What actions will cause the scenario to fail? Don't forget that this is both doing things and not doing things.

Scale for the "Does This Cause Change?" Heuristic

The "does this cause change?" heuristic for determining information has to be used for the whole topic. That might be the same as "for the whole scenario"; it must always consider the scenario, and what this individual topic contributes to the fulfilment of the overall scenario.
In the case of the recipe-with-references structure, the top recipe task's one change, for either Aimée or Eustace, is to go from "I don't know how to make Chocolate Nemesis" to "I do know how to make Chocolate Nemesis". The amount of other information—other topics—necessary to make that true for Eustace is much greater than for Aimée, and the context—personal kitchen, one time, versus restaurant kitchen, series production—is different, but the information, in the form of a change in ability in either of the personae, is the same.

No comments: