20 February 2006
Even bad entries can be good, in context
In technical documentation, often I've seen main entries like "creating user accounts, 325" and "managing settings," where the first word is a gerund that has questionable value. When I'm asked why this isn't a valuable entry, I explain that the ideas of "creating" and "managing" are rather vague. I also explain that if someone wants to know how to create something, he is more likely to look up the something. For example, if you were interested in how to bake a cake, would you look up "baking" or just "cakes"? I believe you'd look up "cakes" first.
Strictly speaking, however, there is nothing wrong with entries like "creating accounts" and "baking cakes," even though accounts and cakes are the more specific and more likely targets of most users. Entries under these generic or vague terms (creating, managing, etc.) become valuable, however, when these terms have greater meaning within their context. In religious texts, the concept of creation (as in "world creation," often written with a capital C) is worth indexing. In business textbook, the concepts of management is worth indexing. And in an instructional cookbook that explains how ovens are used in the most general sense, an entry for "baking" might be appropriate.
The guideline to avoid these general terms, declaring the resulting entries as "bad," ignores context. The argument that readers are more likely to look up the objects of these actions -- "messages, writing" instead of "writing messages" -- doesn't negate the value of having these gerunds as available access points. Actions are still concepts and deserve to be indexed; in technical documentation, task-oriented language has even greater value than average. Consider these entries:
filtering email messages, 000
spell-checking your document, 000
upgrading applications, 000
The reason these work so well is because the ideas of filtering, spell-checking, and upgrading are distinct ideas of importance to technology users. In fact, the above term document is itself a bit vague (whereas file is not), and beginners know applications better as programs. So you can see just how valuable using those gerunds can be. Dismiss them at your peril.
By the way, if you need a practical clue regarding their use, take a look at the full set of documentation and ask yourself if you can use that gerund much more often than you already are. For example, you might have a section where "creating accounts" is obvious, but does that same book talk about the creation of other things, like passwords, files, security filters, network connections, and so on? Just because the word "creation" isn't used (passwords are invented, filters are applied, networks are initiated, etc.) doesn't mean it's wrong. If after some serious thought you realize that you'd have dozens or more subentries under that gerund, consider getting rid of it as not specific enough. Other candidates for nonspecific gerunds in technical documentation include installing, configuring, customizing, opening/closing, hiding/showing, deleting, starting/stopping/quitting, editing/modifying/altering, and accessing.
Strictly speaking, however, there is nothing wrong with entries like "creating accounts" and "baking cakes," even though accounts and cakes are the more specific and more likely targets of most users. Entries under these generic or vague terms (creating, managing, etc.) become valuable, however, when these terms have greater meaning within their context. In religious texts, the concept of creation (as in "world creation," often written with a capital C) is worth indexing. In business textbook, the concepts of management is worth indexing. And in an instructional cookbook that explains how ovens are used in the most general sense, an entry for "baking" might be appropriate.
The guideline to avoid these general terms, declaring the resulting entries as "bad," ignores context. The argument that readers are more likely to look up the objects of these actions -- "messages, writing" instead of "writing messages" -- doesn't negate the value of having these gerunds as available access points. Actions are still concepts and deserve to be indexed; in technical documentation, task-oriented language has even greater value than average. Consider these entries:
filtering email messages, 000
spell-checking your document, 000
upgrading applications, 000
The reason these work so well is because the ideas of filtering, spell-checking, and upgrading are distinct ideas of importance to technology users. In fact, the above term document is itself a bit vague (whereas file is not), and beginners know applications better as programs. So you can see just how valuable using those gerunds can be. Dismiss them at your peril.
By the way, if you need a practical clue regarding their use, take a look at the full set of documentation and ask yourself if you can use that gerund much more often than you already are. For example, you might have a section where "creating accounts" is obvious, but does that same book talk about the creation of other things, like passwords, files, security filters, network connections, and so on? Just because the word "creation" isn't used (passwords are invented, filters are applied, networks are initiated, etc.) doesn't mean it's wrong. If after some serious thought you realize that you'd have dozens or more subentries under that gerund, consider getting rid of it as not specific enough. Other candidates for nonspecific gerunds in technical documentation include installing, configuring, customizing, opening/closing, hiding/showing, deleting, starting/stopping/quitting, editing/modifying/altering, and accessing.
