Are Gerunds in Topic Titles Problematic in Search Results?

I’ve been accustomed to writing topic titles as gerunds (for example, “Configuring the Monitor Display” or “Reformatting Your Hard Drive”), followed by specific steps that would begin, “To configure the monitor display…,” or “To reformat your hard drive….”

However, when I watched how an actual person used my online help file, I noticed he didn’t use gerunds in his searches. He typed his search like this: configure monitor display, or reformat hard drive.

When I search on Google, I also do the same: I use the form of the verb that expresses the action I want to do. I’m not looking to “reformatting my hard drive.” I want to “reformat hard drive.” I want to “configure monitor display.” I want to do something, to perform an action.

Grammatically, I think the gerund is more common. But given that the topic title plays a huge role in the search results, I’m thinking of saying goodbye to gerunds in topic titles. When the user searches for “reformat hard drive” the answer will more readily surface if that’s how I’ve named the topic.

Madcap FlareAdobe Robohelp

This entry was posted in general on by .

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), API documentation (code examples, programming), and web publishing (web platforms, interactivity) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS, email, or another method. To learn more about me, see my About page. You can also contact me if you have questions.

30 thoughts on “Are Gerunds in Topic Titles Problematic in Search Results?

  1. Ryan

    I had never thought of this before. Thanks for pointing that out, because I do the same thing when I search. This is good information to know. I wonder though if Google and other search engines weigh the two words (ex. reformat and reformatting) equally in their search algorithm?

  2. Pingback: This Writer's Friends

  3. Janet

    I don’t know (obviously) exactly how Google does it, but my sense of it is that it looks for various forms of a verb like configure, configures, configuring, configured. That being the case, I’d probably stick with the gerund due to idiom. A title “Reformat your hard drive” is a command and could thereby imply that it’s necessary, even when it isn’t.

  4. Tom

    If you Google “Reformat Your Hard Drive” versus “Reformatting Your Hard Drive,” Google gives you different results. I did a quick test in Flare and Flare seemed to find both forms of the verb. However, I swear I was watching a user search for a specific title without the gerund and the topic wasn’t showing up in the results.

    Here’s a usability question: if the user is looking for a specific keyword in his or her mind, why wouldn’t we use that same keyword in the title?

  5. Dave

    I have a long reason as to why, but the short version goes like this: Ditch the gerund, you’ll thank me later.

  6. Tom

    Dave, thanks for the insight, but you can’t leave my curiosity hanging like that. What’s the long reason why? Any hints that can be expanded a bit?

    Thanks,

    Tom

  7. Dave

    Well, for us it was less about searchability, and more about migrating our content to a topic based architecture. In our case, Dita.

    Previously, we wrote mostly for PDF or Book publishing, and it made sense to follow the common convention of: Gerund, intro, infinitive, intro, steps.

    This resulted in content that looked sort of like this:

    — start of page —
    h1. Saving a file
    This section describes how to save a file.

    h2. To save a file
    To save a file, perform the following steps.
    1. …
    2. …
    3. …
    — end of page —

    OK. So it looks silly here, but I assure you, it doesn’t look as silly in print. And, it’s definitely a common formula for software manuals. Check out Office 97 through 2000 for examples.

    Well, when you try to stick this into a topic oriented system (a la Dita) it quickly becomes apparent that this style of writing is a little silly. In our case, it was doubly obvious because each topic could only have a single title, so this meant having two topics for each instance of the above convention.

    Why do we have two titles for a single task?
    (convention)

    Do we need two introductions?
    (Only if we have two titles, and are printing the help on paper — then we need text to separate the titles, otherwise it looks silly on paper).

    If we have two titles, do we really have two topics?
    (not really).

    Lets say we do have two topics, is their sufficient text in both sections to justify having both topics? There’s an inherent cost in maintaining both. Is it really worth it?
    (often not)

    What about if we just use an alternate titling system, to have the gerund appear in the ToC, and the infinitive appear in the body text?
    (How does that translate to print? We only have one place for a title, which do we use?)

    Assuming that we have to translate to N languages, and each language costs 50 cents a word. Can we justify spending $1.50 * N to have the gerund sentence AND the infinitive sentence? How about an additional $4 * N for the separating sentence?

    Anyhow…. you get the idea.

    In phase 2 of our migration (phase 1 was a PoC), we did a search and found nearly 5000 topics that started with “To …” and nearly 3000 that started with a gerund. In our previous titling, we required each infinitive to be prefaced by a gerund – so the metrics basically meant that we had 3000 use cases, most with one infinitive task, some with more than one, associated with them.

    Well, we did some quick math, and realized that this was a pretty big maintenance issue on our part, and a pretty big localization cost. We had roughly 3000 titles and introductions that may not be necessary.

    So we had some heated discussions about it for a bit, and eventually came to this conclusion: The only reason we have a gerund in the title is because it’s the way it’d always been. It’s common place practice, it’s in the MS Style Guide, and it brings parallelism to the ToC.

    But are these really good reasons? Are the aesthetics of our table of contents really enough of a reason to hang onto this convention?

    I’d say no.

    We put our authors to the test and asked them to do the following:

    1. Look at each example of a task that has a gerund, followed by some text, followed by a ‘To’ task.

    2. Ask themselves: “Does the in-between text add any additional value to the topic. If not, can you delete it?”
    Places where there was value included those places where there were multiple tasks that needed to happen in sequential order, and were prefaced by a description of what was happening at a high level.

    3. Then ask “Is there any value in having a parent level header for this To task?”
    Places where there were value included those places that had multiple tasks that were very tightly grouped (Saving, opening, creating new, etc. could be grouped under “Working with Files”).

    4. If there’s no need for the intro text, and you delete it, and there’s no need for the title, then can you delete it?

    5. Do you hate what you see?
    (Crossing my fingers here for a no, but I offer no guarantees.)

    OK – so what did we end up with after all of that?

    Well, for starters, a bunch of annoyed authors. That was a lot of work.

    Also, we were able to cut back substantially in content, and in the number of words that we have to maintain. Bonus: It was almost all aesthetic fluff.

    The other effect is that now our help files have non-parallel ToCs. This is bad, because they are less pretty. But good, because it readily draws the eye to those topics that are ‘doing’ topics, and those topics that are ‘explaining’ topics. We sort of had this before with the gerund, but it’s more visually obvious now.

    Is this a good thing?

    Well, that I can’t really say. What I can say though, is that I would never consider having two titles again. The cost to write, maintain, translate, and support (additional topics means additional files, means additional work for me) was too high for the relatively low payoff.

    Yup – I think that’s the long version.

    There might be more, but my fingers, and likely your eyes, are getting tired.

    Hope that helps explain the decision a bit. =]

  8. Tom

    Wow, that really is a long explanation. Thanks for taking the time to elaborate. It’s interesting how the DITA model forces you to rethink matters of style. I haven’t embraced DITA yet, so I haven’t entirely experienced this dilemma, but I certainly have been annoyed at writing a topic title twice (Printing … To print…), as you described.

    I’ve more or less followed the convention you outlined above near the top of your comment, but if there is no conceptual text to insert between the gerund title and the “To … ” part, it looks ridiculous — stylistic conventions that are followed for the sake of consistency, but not for readability.

    On the other hand, for those topics that do have conceptual information (and merit double topics in DITA), it would seem an inconsistent approach to write some topics one way, others another.

    You’ve given me more to think about for this problem. However, as I said, I’m not locked into the DITA topic structure. I also haven’t begun to strip out my gerund titles yet — it is quite a lot of work, so I imagine with your project of 5,000 topics, you discussed that for a while.

  9. Janet

    Interesting discussion. I’ll have to think more about Dave’s comments and how they relate to a second kind of search: that of readers (which would be most of them) who scan documents. Which works better for them?

  10. Dave

    Wow. Thanks for the shining example of someone else that is using a similar style. It helps a lot that it’s a pretty big name (other than IBM). I’ll be sure to pass this on to my peers.

    This is very similar to the style that we moved towards. The only real difference is that we begin our titles with ‘To…’. Although, after reading some of your thoughts here, I’d be interested to revisit the discussion on how we title our tasks, and take a look at if there’s a benefit to any of:

    – Saving a file to your desktop
    – Save files to your desktop
    – To save a file to your desktop

    Some of the SEO comments you’ve made make a lot of sense.

    Looking at this guide, it seems very much to me like a Dita guide.

    For example, on Page 33, I see a nice example of a topichead (a container title with no corresponding topic, file, or body text), followed by an explanatory concept, and several tasks.

    Page 35 nicely illustrates a task that is preceded by some additional information. In dita, the element.

  11. Ted

    We have switched to task titles in the imperative mood: “Reformat your drive.” “Share a document.” Mostly, like Dave’s team, to reduce redundancy, but also there’s a matter of what kind of authorial voice works with active, task-oriented writing. An imperative sentence comes across like a helpful, may I even say proactive, suggestion. A gerund gives the impression of sitting around waiting for the user to hit on something and then helping them out with that. Since we are in the middle of generating a lot of new content, we decided this would be a good time to make the switch, and it’s helped ease our DITA conversion at the same time as it’s added a certain zip to our task topics.

  12. Tom

    Thanks for commenting, Ted. I agree with you that the imperative mood seems more proactive, task-oriented, and immediate to the user’s need.

  13. Tom

    I think “Save files to your desktop” is more readable than “To save files to your desktop.” When you have tons of topics that all begin with “To …,” it gets a little tiresome on the eyes.

    I also think this is how Microsoft styles their drop-down hotspots.

  14. Ryan

    Great topic. I am coming around to the view that gerunds aren’t the best way to describe a task. You are correct about Google and our habits. I recently had to look up something for TurboTax and I didn’t enter “Adding 1099 to TurboTax,” I entered “Add 1099 to TurboTax” to get the broadest results.

    I am inspired to start dropping the gerunds, thanks.

  15. Karen

    I’m using DITA on a client project. Early on, I discovered users were completely inconsistent in how they referred to what they did, but entirely consistent with what they did it _to_. ie depending on who you ask, they could be “printing,” “generating,” “running” or, in one case, “compiling” a report. But they all end up with a report.

    I also discovered they use various terms incorrectly, and they’re not about to change their habits: they say they’re importing, when they’re actually downloading, and they don’t know what “uploading” means at all. They just “download” both ways. But whatever they’re doing, they’re doing it to a file.

    I gave up worrying about verbs, whether gerunds, infinitives, or imperatives at all, and adopted a practice preached by professional organizers: organize around the noun. I title a generic DITA topic with the noun, and then gather related info into that topic using gerunds with the plural for concept material, and infinitives in the singular for task material. I use nouns for the reference topics, too. So I get, for instance:

    Reports-
    .Generating reports
    ..To generate a report
    …User-generated reports

    .Saving reports
    ..To save a report
    etc

    The keyword, electronically and visually, is always the same, in singular or plural, no matter what the action is.

    I’ll add that I gave up on the “About…” model (“About printing reports…” etc), which I notice the BlackBerry guide uses, when I noticed how it slowed down my own ability to scan a long list of topics. I figured if I couldn’t find the info swiftly enough, and I was the one who’d written it, my readers would get agitated in no time flat. (Besides, using “about” in non-fiction of any type strikes me as entirely redundant, anyway.)

  16. Rajdeep

    Wow! this is interesting and really worth debating on. I come from a writing background and off-late have been doing quite a bit of research and conducting mock usability tests on documentation. The first thing that a user does is click the Search tab and put in exactly the words for his assistance. Say one of his tasks is to reboot the machine, he types in “reboot the machine’ starightway.

    One of the conclusions that I made from my tests is that the users wants easy and clear steps. Usage of verb forms highly supports his actions and therefore, I am of the opinion that we need to stop using gerund for the heading levels.

    If the user doesn’t get the required assistance, will the gerund in heading levels be of any use? I don’t think so :(

  17. Cosmin

    1) Infinitives: to much of “to” and the user can’t concentrate if it searches for a specific topic in a printed manual for example.

    2) Gerunds: I prefer using them in titles (however, I use the old-fashioned style of product-oriented user documentation). The first word in title of topics should be the one that interrests the user (the action itself). There’s however something disturbing when using gerunds: the “ing”…

    3) Imperatives: I do not like using them because, as Janet said in one of the first comments, it may sound like a command, a must-do thing. This may sometimes confuse the user. A plus is (as with gerunds) that the user sees in the first word of the topic what’s s/he looking for.

  18. Cosmin

    I also have a question. I need to describe the actions the product can take on infected files. To this purpose, I use a table:

    Action | Description
    ———-|—————–
    Disinfect |
    Delete |

    In the description field I can think of 3 ways of describing the action:

    1) Disinfect – To disinfect infected files.
    2) Disinfect – Disinfects infected files.
    3) Disinfect – Infected files are disinfected.
    Delete – Infected files are deleted immediately.

    What variant should I use/you recommend me to use/it’s more appropriate to use/it’s standard to use?

    The first one does not seem to be a description (according to the table heading – does not seem to fit there). The second one is active voice (so it’s better), but one may ask who’s performing the action (a possible answer ” Disinfects infected files”). The third option is ok; however, is in passive voice making it hard to read, especially since I’m using it quite often to describe product options.

    Although I think the third variant is the most correct, I tend to use the second one for ease of reading. What’s your opinion?

  19. Ted

    Cosmin, this would be a good place to use the principle of putting the reader in charge. Write about what the user is doing, not what the system is doing. It’s not that the product is disinfecting files, it’s the user who is disinfecting files with the help of the tool. None of your alternatives allows for that perspective.
    However, you have a deeper problem here: you are repeating the defined word in the definition, twice over. When you do this, the reader naturally gets the impression that this explanation is pro forma, and skips over it. (“So, ‘disinfect’ means to disinfect something that’s infected? You don’t say!”) To bring real value to the situation, show something about the action that is not already obvious from the label. Maybe like this:
    1) Disinfect – Get rid of any viruses that have been detected.
    2) Disinfect – Clean up compromised files.

    Ted’s last blog post..The W3C’s new SEX 1.0 specification – O’Reilly XML Blog

  20. Cosmin

    Thanks for your advice! Especially for that concerning circular descriptions. I think I use them in some other places to.

    One more question: to what extend should I use the principle of putting the reader in charge? Do I have to use it when describing all product options? For example, I have a lot of options that begin with “scan”: “Scan boot”, “Scan for spyware” etc. I’ll probably end up using circular descriptions. Should I use passive voice in these cases?

    Tom, sorry for bringing my questions onto your blog.

  21. Tim Mantyla

    Great discussion.

    The main idea is making the instructions user-friendly. I like the Blackberry instructions linked above, and I’ll try to use this model in my work.

    Because of the complex, mongrel nature of English (one reason it’s among the most difficult to learn for non-native speakers–and why spelling is just plain difficult for most people) maybe it’s just impossible to make documents perfectly easy to use, search and organize, given the kinds of English constructions available.

    I wonder how tech writing fares in other languages, whether this is an ethnocentric debate that applies only to English.

    Do writers and editors have these kinds of debates in Mandarin, German, Hungarian, Finnish, French, Urdu and Italian? Are there any languages so perfectly organized that it’s obvious what voice to use, and users have no confusion when searching?

    Organizing the topics around nouns looks promising, and so does eliminating gerunds.

    Here’s an attempt to summarize the principles discussed above:

    1) You don’t have to use absolutely correct English, but English that works for the purpose
    2) You don’t have to make wording consistent for the sake of consistency if it hampers the user/reader
    3) Make the instructions or content fit the way people use it (e.g., find out search terms people use and write to fit that)

    This humanizes the content and it makes it work best in the users’ hands.

    A historical perspective on user-friendliness:
    User-friendliness in technical products and their instructions is a seeming innovation that has been around since the dawn of time. It’s also known as “The Golden Rule,” “The Platinum Rule,” “Live and let live,” and “Do unto others as you would have them do unto you.”

    The Ten Commandments are written in a fairly user-friendly way, although the “Thou shalt…” form seems archaic when compared with today’s informality. (This is not to say it’s always easy to follow every commandment!)

    Now that the Internet has fostered user-generated content and conversations between producer/marketers and users/consumers, it’s easier to ensure people can use the products or services by using their feedback.

    This may be the Age of Participation or Age of Conversation, not merely the Information Age. Communication isn’t one-way, or even two-way now, but multi-way. It’s multi-dimensional communication.

    Tim Mantylas last blog post..Watch for these upcoming posts!

  22. The_Football_Maniac

    Hi,

    Yes this is me ranting but with the cost of my season ticket going up this year (again), huge sums of money being thrown around by Arabian oil magnates and American insurance salesmen in an attempt to buy the title / Champions League and Sky’s nauseating coverage, it seemed to me that the guys behind this site have got a decent idea.

    It’s a campaign to see a salary cap introduced in European football and to be honest, I think it makes some very good points.

    The argument is put forward very well, it’s got support from some pretty high-profile corners and it seems to be a campaign that has the game as a whole at heart.

    Put simply, there are too many clubs running up ginormous amounts of debts to pay unsustainably high salaries to players whilst at the same time, the big names are able to cream the best of the talent to the detriment of the competition.

    The site is Footballers Wages and personally, I agree with the idea of having a salary cap. It works in other sports and not only will it save some clubs from themselves, but it might at least bring footy back to being a contest decided on the pitch, rather than in the boardroom.

    Thanks

  23. Marcia

    This discussion has been enormously helpful. Our tech comm group is making the transition to DITA, and we’ve been puzzling over task-heading syntax (gerunds vs. infinitives vs. imperatives). We’ve also been struggling to figure out how to incorporate our “stem sentence” headings — “TO DO THIS” heads directly preceding Step 1 — into task topics. Thanks to all who have contributed insights, arguments, concerns, links, and examples.

  24. janiceenberg

    Hello everyone i am completely new to this forum. Interested in learning many new things. Hope we all will share our knowledge and talk about different concepts in this forum.

  25. blaxemnaxia

    I’ve heard about this game but i don’t know anything about it, can anybody tell me few words for it? Here is it for those who don’t know what im talking about, Mahjong.

    Thank you in advace, i’ll appreciate every review about it!

Comments are closed.