Topography, Muffins, and Chunking

Before I start a section hike, and sometimes just because I have the itch even when no hike is planned, I look at the topo maps for one section or another where I want to go. It's not just for fun — although it is fun — it's to break down a hike into manageable chunks of terrain that I can walk each day.

This activity in technical communications is called chunking, and it's central to topic-based authoring. Unfortunately, many writers get this wrong, and the tendency is almost always to create too few chunks that are individually too large.

I understand this mistake well — I make it often when planning a hike.

In topic-based writing, much attention is given to chunking content into topics, which is important, but does not in itself go far enough. Chunking is a practice that should be applied at multiple levels:
  1. Chunk guides into volumes or multiple deliverables using a logical organizing principle, often corresponding to audience.

    For example, your product might have a user's guide for general-purpose users and an API reference for programmers, or you might deliver separate guides for different installation platforms.

  2. Chunk deliverables into "chapters" or topic groups as appropriate for the content, usually based on goals. Often, chapters have multiple tasks that are used in some combination to achieve a single broad goal.
    Note: Even in topic-based authoring, the language of books is pervasive, partly because most of us still generate PDFs, and partly also because terms like book and chapter provide a useful shorthand for the scope of the content so contained.

    For example, you might have different chapters for installing, configuring, managing users, and creating reports, depending on the functionality of the product you are documenting.

  3. Chunk chapters or topic groups into individual topics that address a single atomic task or concept.

    For example, a chapter about managing users might have topics for creating users, changing user permissions, and removing users.

  4. Within topics, chunk your content into paragraphs, sections, lists, and tabular information that are granular.

    This helps your users in two ways — it makes your content easy to scan for the needed conceptual or reference information, and it helps users follow tasks exactly without missing key steps.

Cookbooks are often excellent at chunking at the first three levels: typically, you will find chapters devoted to appetizers, fish, meat, poultry, and desserts, each containing self-contained topics that provide exactly the information required to prepare a single dish.

Equally often, however, cookbooks fail miserably at the final level. Recipes are organized into two sections: a list of ingredients, and the steps required to make the dish. The ingredient list is usually done well; after all, it's a list of stuff you need, and how hard is that?

The steps, however, are another story. It's my belief that most of why certain people believe they "cannot cook" is that the procedures in many recipes are written so poorly that simple tasks seem insurmountably difficult. A muffin recipe chosen at random from one of my favorite cookbooks illustrates this well:

Original Steps

  1. Adjust oven rack to lower-middle position and heat oven to 375 degrees. Whisk flour, baking powder, baking soda, and salt together in medium bowl; set aside.
  2. Cream butter and sugar with electric mixer on medium-high speed until light and fluffy, about 2 minutes. Add eggs, one at a time, beating well after each addition. Beat in one-half of dry ingredients. Beat in one-third of yogurt. Beat in remaining dry ingredients in two batches, alternating with yogurt, until incorporated.
  3. Spray 12-cup muffin tin with vegetable cooking spray or coat lightly with butter. Divide batter evenly among cups. Bake until muffins are golden brown, 25 to 30 minutes. Set on wire rack to cool slightly, about 5 minutes. Remove muffins from tin and serve warm.

I cannot fathom what principle the writer used to decide that this procedure is constituted of only three steps. It might be prep work, making the batter, and baking, but even that paradigm (as unhelpful as it is to the user) fails when you consider that combining the dry ingredients is also part of making the batter, and coating the muffin tin is arguably prep work.

If you chunk the procedure to each actual step (and put the prep work first), you get a procedure that is easier to follow.

Chunked and Reorganized Steps

  1. Adjust oven rack to the lower-middle position.
  2. Preheat oven to 375°.
  3. Spray a 12-cup muffin tin with vegetable cooking spray or coat lightly with butter.
  4. Combine the dry ingredients.

    In a medium bowl, whisk flour, baking powder, baking soda, and salt together; set aside.

  5. Cream butter and sugar with electric mixer on medium-high speed until light and fluffy, about 2 minutes.
  6. Beat in eggs, one at a time, beating well after each addition.
  7. Alternately beat in dry ingredients and yogurt in three batches, until incorporated.
    1. Beat in half of the dry ingredients, followed by a third of the yogurt.
    2. Beat in half of the remaining dry ingredients, followed by half of the remaining yogurt.
    3. Beat in the rest of the dry ingredients, followed by the rest of the yogurt.
  8. Spoon batter into muffin tin.
  9. Bake 25 to 30 minutes until muffins are golden brown.
  10. Set on wire rack to cool slightly before serving, about 5 minutes.

The lesson here is that chunking is important at all levels, not just when determining the scope of a topic. Maybe I can apply this idea when I'm looking at the topo maps. It would be nice to schedule rest stops for each day.