Help, I can't find it in the index!

When you need information from a manual or a help system, how do you look for it? Many of us will use the index first, if there is one. Why?

A table of contents is the writer's view of the book. It describes the structure. It tells a story.

If you need to know one specific bit of information, you may not know exactly where you are in that story; and you probably don't care. You just need to know how to change the frabbetizing configuration settings on the MumbleCo unit, and you'd prefer to get it done before you stop and go outside for a smoke.

If your company has recently switched to this product from a competitor's product, you may not know that the appropriate terminology for the setting you want to change on this fine product is "frabbetizing configuration". You may still be thinking in terms of the competing unit from Behemoth Inc., which calls the equivalent setting on its machine "whatsit settings".

If the manual for your new MumbleCo unit has a good index, it doesn't matter whether you know where you are in the table of contents story, and it doesn't matter whether you're up to speed on MumbleCo terminology. You can look up the term you know - "whatsit settings" - and the index teaches you, very gently, "See frabbetizing configuration." And lo, when you look up frabbetizing configuration, there it is, with sub-entries that point you to all the things you might want to know about it.

If the author of the manual has given the index short shrift, you're on your own. Maybe you should take that break before you try to find the information you need.

Fairly often, the index does get short shrift, like all the other things at the back of the book. Making a good index is labor-intensive; there's no good way to automate it, regardless of what the makers of authoring tools would like you to believe. It takes a person asking "What is this paragraph about? What would I have been looking for if my search led me here?" Fairly often, the index entry is a phrase that does not occur in the indexed material. But the fact that it may take 6 to 8 hours per page to create the index does not mean you should skip it.

The index is a reader's random-access information discovery tool, and it is (or should be) the writer's teaching tool. With all due apologies to Adobe, try this experiment: Look for a specific bit of information, using generic terminology, in the help for an Adobe product. For example, in Illustrator, how do you move a vertex to change a shape? You'll see what happens when you overlook the teaching aspect of the index. In Adobe-land, you have to know the terminology already to find the help you need. But who needs the most help? People who have no prior experience with the product, and don't know the terminology. In all fairness, Microsoft is just as bad; I never have been able to figure out if there is a way to change rows to columns and vice-versa in Excel when I decide I've structured my spreadsheet badly. And I have never been able to make heads or tails of the bookkeeping software I bought last year, because I don't know the terminology. In each case, the index fails in its teaching function - it doesn't include plain language that refers me to the specialized term.

The lack of a well-designed index in a manual or help system makes the whole product less usable.

When you work out the schedule for writing a manual or help system, include the time to create an index. In my experience, it will take about a sixth of the total writing time; your mileage may vary. But no matter how much time it takes, do it. Your readers are counting on you.

Recipes, assumed knowledge, and indexes as teaching tools

Consider: Recipes and cookbooks are one of the oldest forms of technical writing. They tell you how to complete specific tasks, and what results to expect. Cookbooks also have explanatory material to help you understand the techniques and terminology in the recipes, along with conceptual information - why you knead bread but handle pie crust dough as little as possible, which ingredients can be substituted for others.

When my Grandma Mulholland passed away years ago, I inherited her recipe box - and realized that we technical communicators can learn a lot from trying to follow old recipes. Grandma's fudge recipe (transcribed here exactly as my grade-school educated Grandma wrote it) provides some examples.

Quick Fudge
2 1/4 C Sugar
1/2 Cube butter
1 small can Carnation milk = 2/3 cup
Boil 5 minute stir constantly
Remove from heat, add 1 1/2 C Mineture Marsh mellow and 1 Pkg of Choc Chipps - 1 t flavoring
Beat untill all disolved. Add 1 C Nut Meats & stir them in
drop by spoonfull on Wax Paper...buttered dish - cut when cool

Grandma made a lot of assumptions about what people know and what they can buy at the grocery store. Fortunately I could remember what was available in the average grocery store in a smallish city in Indiana back when the world was a large place and other parts of it were far, far away, so I was able to figure out what this all meant.

The 2 1/4 C sugar was pretty straightforward; it meant granulated white cane sugar, the default choice of sweetener in the midwestern USA during the middle of the 20th century. If Grandma had meant brown cane sugar, she would have said so - and she never encountered any other kinds of sugar.

Half a cube of butter? A bit tougher. Looking at the quantities of the other ingredients, I decided that was half a stick: 2 ounces, or 4 tablespoons.

Carnation milk would be evaporated milk. Two kinds of milk came in cans when my Grandma started using this recipe: Carnation milk, which was evaporated; and Eagle Brand milk, which was condensed and sweetened. I remain grateful that Grandma saw fit to note that a small can is 2/3 cup.

Miniature marshmallows are still with us, so that was no problem.

I had to think hard about the chocolate chips. These days I buy them in 24-oz bags, but they weren't available in such large packages when Grandma was still making fudge. I racked my brain. Grandma was not one for buying large quantities of stuff and then keeping it around. Ah - so it would be the smallest size, otherwise she would have said what size bag. So it's six ounces of chocolate chips. I used six one-ounce squares of Baker's chocolate instead, and the fudge came out right.

That brings us to "1 t flavoring" - a teaspoon of...what? Well, vanilla, again because that was the default in mid-20th century cooking in the midwestern USA. You put it in most sweets, and it was nearly mandatory in anything with chocolate.

And that cup of nutmeats - that had to be chopped walnuts. If you climbed in a time machine and went to a Kroger's or A&P in Indiana circa 1965, right beside the six-ounce bags of chocolate chips, you'd find bags of chopped walnuts. There would probably be slivered almonds as well, but they were for exotic stuff like green bean casserole. You'd never have put them in fudge. And the pecans were out of the question. Only a Southerner would put them in fudge.

So here I sit, nibbling on fudge that tastes exactly like the stuff that Grandma made every Christmas, and reflecting on how much I had to know to make that recipe turn out right.

It's making me think about what a hard time I've had learning some popular software tools, such as Adobe Illustrator and Microsoft Excel - in each case, there was a body of assumed knowledge that I did not have. In each case I had trouble using the help because I did not know the names of things. And in each case the help index failed in its teaching function - I could not look up familiar terms and get "See" or "See also" entries that pointed me to the help I needed. Sometimes I muddled through until I stumbled upon something that worked, sometimes I asked a friend, sometimes I gave up.
Well, fudge.