I'd Rather Be Writing » chunking

Topic Chunking and The Broken Alarm Clock

Tom Johnson — Wed, 27 Apr 2011 13:48:24 +0000

It’s been about 9 days since my last post, and yesterday my colleague leaned over and asked why I hadn’t been posting — was something wrong? He himself has been working on a novel, so he hasn’t posted anything for a month.

No, nothing is wrong. I always chuckle when I see blog posts in which people apologize for not posting on their blog, or when they provide reasons for their lack of blogging activity. I chuckle because it’s like, hey, I didn’t miss you. I have 1000+ unread posts in Google Reader and content overflowing on Twitter, books from Amazon, and other sources. There’s no dearth of content on the web, so your short absence of content isn’t something I’ve been agonizing over. I suspect the same is true for my readers.

If you really want to know, though, I’ve been exhausting my creating energy writing a debut article for work. I’m still waiting on the outcome, but it involved doing some historical research, and that kind of stuff you just can’t crank out with clever typing.

Now, on to the broken clock. After my last post about rocks and cairns and chunking, some people thought it was funny that I went to Arches National Park and all I took were pictures of dinky rock cairns. So for those waiting for something more camera-worthy, check out Park Avenue.

Park Avenue in the Arches

And if you prefer people in your pictures, here I am skydiving off a rock in Sand Dune Arch.

Skydiving off Sand Dune Arch. The sand below is really soft. Otherwise I wouldn't do this.

I will spare you the 60 to 70 pictures of the baby crawling through the sand, as well as the other hundred pictures of my other kids doing all kinds of funny poses with rusty-orange arches in the background.

But digital pictures are not entirely irrelevant here. In David Weinberger’s Everything Is Miscellaneous, he says the digital camera has encouraged people to take many more photos than they normally would. After a while you end up with thousands of photos on your hard drive, with almost no way to order or arrange them. Do I tag the above photo Arches? Utah? 2011? Jumping? Age 35? Soft sand? Rusty orange rocks? Sandstone? Falling? About the only thing you can do, without a specific metadata strategy, is tag the photo haphazardly. (I actually don’t tag my photos at all, really. They just sit in various folders.)

But the scenario, if I were to tag my photos, is relevant to the ongoing discussion about chunking. The trend in previous comments I received was that your metadata strategy informs the size of each topic. If your metadata requires you to identify certain characteristics, then naturally your topic will need to be a certain size in order to accommodate that metadata. This makes sense to me.

But the most thought-provoking comment was by Mark Baker, who pointed me to a post on his site comparing granular topics to a broken clock. Mark says that as you start dismantling an alarm clock into its pieces, the pieces soon become meaningless in isolation. The broken clock is similar to a topic: the more granular it becomes, the less meaningful the topic becomes to readers. You also have less potential for attaching metadata to the topic. Mark explains:

Now start taking it [the alarm clock] apart. First you will disconnect various assemblies: the case, the clock mechanism, the ringer. Some of these, at least, could still have interesting metadata attached to them. But you continue, taking each of these assemblies apart until what you are left with is a collection of screws, gears, and several pieces of bent metal about which you can say nothing meaningful other than that they used to be part of an alarm clock. (Why Fine Chunking and Rich Metadata Don’t Mix)

I couldn’t find a picture of a disassembled alarm clock, but here’s a flayed alarm clock below. You can see all the components here — capacitors, transistors, wires, tubes, square things, bands, and other parts. Would it really be wise to isolate each one as a separate topic?

Look at all the pieces in an alarm clock. Would it make sense to separate them out and sort/arrange/call by various pieces? Probably not -- unless you're an alarm clock maker.

Keep in mind that the broken alarm clock is a metaphor, and all metaphors break down at some point. But it’s quite a good metaphor since many of us do not understand the insides of alarm clocks. In fact, if you were to disassemble any technology in my house — the refrigerator, a DVD player, a digital camera, an automatic pencil sharpener, etc, I probably couldn’t make much sense of the individual components. They are meaningless in isolation.

A while ago I was reading DITA 101, by Ann Rockley, Charles Cooper, and Steve Manning. In the introduction, the authors assert that a well-written topic can stand alone in nearly any medium. A well-written topic is versatile in its placement, and is a logical unit in and of itself. It doesn’t require much context to make sense.

To accomplish this self-contained unit of information, I think a topic has to be a fairly decent size. It probably wouldn’t be a short standalone paragraph, nor would it likely be a short list of three steps. In my mind, it would be a somewhat sizable topic — probably a conceptual description followed by a list of task steps. One needs a certain amount of substance to prevent the type of content that seems fragmented and incomplete to the user when viewed alone.

That’s it for now. By the way, if you’re going to the STC Summit, I’m giving a presentation titled Organizing Help Content: Breaking Out of Topic-Based Hierarchies on Tuesday at 4:00 pm. In it I hope to present the ideas I’ve been exploring in my Organizing Content series. Unfortunately my presentation is at the same time as Karen McGrane’s We Are All Content Strategists Now and, judging from what I saw on Vimeo, she looks like a really good speaker. So my Summit audience may be a passing janitor and an assigned room monitor, but that’s okay. Expect to see more posts in this series on my blog.

Also, I can see that the topics are moving toward metadata and taxonomy. If you have any good recommendations for books on metadata (in the context of technical communication), please let me know. I am finding that, despite the abundance of well-written blogs, books are sometimes more enjoyable to read in the long run.

Blog Sponsors

The Importance of Chunking for Sorting

Tom Johnson — Mon, 18 Apr 2011 14:39:25 +0000

If you want to be able to sort information by various classification schemes, such as by most popular, or by role, or by problem, your content has to be chunked in a granular enough way to facilitate the various means of sorting.

Consider a work that is one large book, with no chunks at all. In that case, it would be impossible to sort anything, because you have just one object. With one object, the only pattern you can configure is itself. But if you have a handful of objects, you can arrange those objects into as many patterns as you want.

To use an analogy, let’s say you have a pile of rocks. If you have 1,000 small rocks, the potential number of patterns you can configure with the rocks is infinitely greater than the patterns you can configure with just a few rocks.

I noticed this in a recent trip to Arches in Moab. While walking along trails, we saw a lot of rock piles called cairns that act as guide points. The cairns can be stacked and arranged in myraid ways, because they consist of little rocks:

But the big rocks are much more pattern-limited. They mostly just sit there, alone:

Thus if your goal is to enable a variety of patterns or classification schemes, so your users can choose from myriad classifications, according to their individual needs, you must chunk your content in a granular enough way to facilitate the classifications.

Granular chunking poses some difficulties for help content, because if you chunk things too small, the help system becomes arduous to navigate. If each page contains just one topic, you end up with so many pages, navigating the pages will give users a headache.

To avoid this, on my calendar help wiki, the Viewing Calendars page has the following topics on the same page:

All of these topics appear on the Viewing Calendars page.

Now, suppose I want to manipulate this content on a more granular level. Suppose the “View Calendars of Other Wards” topic is a popular topic; the “FAQ” issues would be appropriate in a problems-based classification. The “About Subscribed Calendars and Subscribed Locations” belongs to a conceptual table of contents. The “View Churchwide Calendars” belongs to a “Coming Features” type of organization, and so on.

In short, let’s say I want to add metadata to each of these sub-topics so that they can be sorted, rearranged, recompiled, or otherwise organized in different classification schemes. If they are compiled in one giant topic, they can’t be manipulated at all except on a more macro-level. This is why chunking is such a fundamental principle to technical writing, because without small chunks of content, you don’t have many options for manipulating it.

Whether you use a wiki or not, deciding how granular to chunk your content is a challenge. For example, on Microsoft Word’s Help, this is the topic for Changing or Setting Page Margins.

This topic on working with margins really contains five separate topics.

By combining these five topics into one topic, it becomes more difficult to manipulate the individual sub-topics as their own topics. The metadata you add to this topic must account for all the sub-topics within this topic.

Now consider the opposite strategy. Let’s make each subtopic its own topic. You can see the effects of this approach in the following Office help search:

When you chunk things in a granular way, it becomes harder to find the chunks, and you lose some context.

Here the topics on formatting are all chunked into their own topics, so you end up with Clear all text formatting, Show or hide formatting marks, Apply strikethrough formatting, and so on. When a user clicks on a topic, the topic is short, such as the following:

This is a short topic. This is all that's there.

This short topic either answers the user’s question or it doesn’t. There’s not much room for error, since no similar topics are grouped together. If it’s not the right topic, the user must return to the list of results and click another, and another, and another until he or she locate the right topic.

In contrast, if you combine a larger number of topics together on the same page, you give more context to the user. He or she can read conceptual introductions followed by a handful of sub-topics that all deal with the general topic. The user can easily scan down the subheadings to find the right sort of task for this topic. But it’s harder to manipulate each individual sub-topic separate from the larger topic. And your metadata can’t describe each of the individual sub-topics but must cover the larger topic generally.

Chunks that Consist of Chunks

I’ve been contrasting big chunks versus little chunks without acknowledging that big chunks can consist of combinations of little chunks. So in each of the examples above, the topics can exist separately but be grouped together into the larger topics that you see.

With Mediawiki, this method of reuse is called transclusion. Last week, convinced that I needed to chunk each topic more, I separated all the topics that you see in that first calendar screenshot onto their own individual pages. I then “transcluded” these chunks to form a longer page.

Currently, from the user’s point of view, it looks exactly the same. But really, I can now arrange and manipulate these chunks however I want because I can apply unique metadata to each one of the topics.

However, this poses a new problem: searches will find the individual chunks and the larger pages that combine these chunks, which means content will be in multiple places rather than one place.

The Collage and the Painting

Don Day’s post on The Collage and the Painting describes how search becomes problematic with little chunks. Day is writing in the context of DITA, but the challenge of working with small chunks is the same. Day writes,

A common talking point about DITA is how the topic-referencing architecture makes it easy to reuse topics in new maps of information. By extension, searching on a facet of interest should bring up a collection of topics that you can read as a focused subset of a larger whole. Print it as a PDF, or output it in eBook format, and you’ve got some good reading for the commute or for the weekend. But how practical is this vision?

The flaw in the theory comes from loss of context when you pull a set of topics by query. Imagine doing a web search on a subject of interest and then printing the whole list of hits, as is, into a single PDF for later reading. Obviously you will have the problem of duplicated content, possibly some older and less reliable content, a good deal of discussion by people who are not experts on the subject, organizing the hits in a reasonable manner (by timeline, by author, in a hierarchy) and so forth. Metadata might help in preserving bits of a former organization or rationale, but the new use might be totally different from how any of that content was originated. Bringing order out of disarray is the whole drive behind the growing trend of Content Curation.

Don Day uses the metaphor of the collage and painting to distinguish between small topics pulled together without order and a larger chapter that provides context and sequence for each of the topics.

In other words, if you pull together all topics that have specific metadata, such as all topics related to scheduling events, you may get an unordered collage of topics. The order of the topics may not reflect any kind of sequenced or arranged reading. The list of topics no longer forms a larger, well-written chapter that contextualizes each topic, but rather may seem like little scattered objects here and there.

The effect might be compared to taking an entire book and ripping out all the pages and throwing them on the ground, mixing them up, and then reading the randomly arranged orders. That reading experience is dizzying and un-fun.

In sum, when you run searches on all the topics together that have similar metadata, you end up with assortments of small chunks that lack the continuity and context of a larger chapter or book. This simply seems to be the tradeoff of chunking your content. Your search results become more like a collage, but you have more flexibility in how you arrange your topics.

Blog Sponsors

Leaning Towards Longer Topics and Shorter TOCs

Tom Johnson — Tue, 23 Sep 2008 04:36:09 +0000

Everyone knows it’s a good practice to chunk your help material into discrete topics, but how granular should you chunk it?

Take a look at this Microsoft Word 2007 help topic on inserting headers and footers.

Example of a Quick Menu from Microsoft Word's Help on inserting headers and footers

Although inserting headers and footers is the main task, the topic really has 11 related tasks:

Insert the same header or footer on each page
Make the first page header or footer different from the rest of the pages
Use no header or footer on the first page
Make the header or footer different for odd and even pages
Make the header or footer different in each section or chapter
Change the contents of a header or footer
Insert a page number
Insert the file name of the document
Insert the document title, author’s name, or other document property
Insert the current date
Remove the header or footer

The author could have created 11 separate topics. Do you agree with Microsoft’s decision to group all of these subtasks into the same topic? Or would you rather explore each subtask as a separate topic in a table of contents?

Although the practice of single sourcing encourages chunking of tasks, if you won’t be reusing the subtasks or related tasks independently, there’s little reason to separate them out into discrete topics. Forcing all of these subtasks into separate topics would severely bloat the table of contents (TOC), rendering it not only less usable, but also more intimidating. Your application’s apparent complexity would magnify.

Separating each subtask into its own topic often forces users to click in a non-linear pattern from topic to topic as they search for the right task. This nonlinear clicking can give users a headache. It’s part of the reason why reading online is more strenuous than reading a book. Books provide more of a hierarchical layout and logical progression of ideas. In contrast, the web is a scattered maize.

Consolidating subtasks into one topic also improves the user’s ability to find topics. With fewer topics in the TOC, the user can actually browse the TOC and find the right topic. But even if the user reverts to keyword searches, the longer topics will have greater keyword density and more likely rise to the top in search results.

I sent a question across Twitter the other day asking whether anyone had done research into this issue, and Brenda Huettner pointed me to a Web Usability Guidelines reference book. Chapter 8 echoes Brenda’s response that “it depends.” The authors say that older people are slower at scrolling, but comprehension may be better because the user remains on the same page. Here’s an excerpt:

Guideline: Use longer, scrolling pages when users are reading for comprehension.

Comments: Make the trade-off between paging and scrolling by taking into consideration that retrieving new linked pages introduces a delay that can interrupt users’ thought processes. Scrolling allows readers to advance in the text without losing the context of the message as may occur when they are required to follow links.

However, with pages that have fast loading times, there is no reliable difference between scrolling and paging when people are reading for comprehension. For example, one study showed that paging participants construct better mental representations of the text as a whole, and are better at remembering the main ideas and later locating relevant information on a page. In one study, paging was preferred by inexperienced users.

Sources: Byrne, et al., 1999; Campbell and Maglio, 1999; Piolat, Roussey and Thunin, 1998; Schwarz, Beldie and Pastoor, 1983; Spool, et al., 1997; Spyridakis, 2000.

In other words, each time a page loads, you interrupt the user’s thought process. By remaining on the same page, the user can better grasp the concept as a whole.

Thanks for the resource, Brenda! In the studies, the content consisted of web pages rather than help material. Some of the examples for scrolling depict long, sophisticated pages — quite a bit more hairy than the Word example above. Still, I agree with the general findings and think they apply to help authoring.

My colleague Ben Minson, however, raises an important objection to long topics. He says,

In reality, people don’t want long topics. They want to think that procedures are short and simple. Long topics intimidate people and make them reluctant to consult the documentation in the future. (“Long Topics: A Help Author’s Crime Against Humanity“)

I agree that no one wants to be confronted with a massive topic when all they need is information to complete simple task. However, adding a quick topic menu at the top, similar to the following image, seems to solve that problem, doesn’t it? The user can jump immediately to the relevant topic, rather than meticulously scrolling down and checking each heading.

[image title="Example of a Quick Menu" size="full" id="2017" align="left" linkto="viewer" ]

Overall, in my experience, it’s easy for a help’s TOC to grow successively larger as you think of more and more scenarios, possible tasks, and concepts to explain. But if you reach the end of the project and see that your initial 50 topics have grown to 250, I think something’s wrong. Most applications aren’t that complicated. When users expand the TOC and find a seemingly infinite number of topics, it’s the equivalent of the disheartening “thud” from a long printed manual.