Three Reasons to Favor the Infinitive in User Assistance

Verbs that can be made gerunds by adding ingThree Reasons to Favor the Infinitive Form

In user assistance titles and text, should you use the present participle (ing form), or the infinitive, for example; Baking a cake, or Bake a cake? Here are several reasons to use the infinitive form rather than the ing form.

1. The infinitive is shorter and easier to understand

The infinitive has fewer letters than the present participle, and easier to read and understand. The infinitive imposes a lower cognitive load, and has a faster comprehension speed. Here are two examples; set versus setting, skip versus skipping. Which would you rather do; set the table or be setting the table, skip this step, or be skipping this step?

Here’s another example.

Stopping, Restarting and Continuing Numbering (41 letters)
Stop, Restart and Continue Numbering (32 letters, or 22% shorter). Shorter is generally better, but how can we quantify better?

Flesch-Kincaid Readability Scores

We can measure readability using the Flesh-Kincaid score. Let’s compare some examples using Readability-Score.com and their Flesch-Kincaid Reading Ease and Flesch-Kincaid Grade Level.

Copying and Pasting Rows – Flesch-Kincaid Reading Ease 54.7, Flesch-Kincaid Grade Level 6.6
Copy and paste rows – Flesch-Kincaid Reading Ease 75.9, Flesch-Kincaid Grade Level 3.7

2. Write from the audience perspective. How do we search? What do we want to do?

As the user assistance writer, your task is to describe the process of (insert present participle here) (insert noun here).” For example, what’s the process of starting the engine. Meanwhile, your audience may be asking themselves, “how do I start the engine?” This is what they search for. If you’re not a writer, you may have heard about Voice of the Customer campaigns. These are designed to help company associates think/act/listen/speak in the voice of the customer. When we use the same terms as our users/clients/customers, it obviously aids understanding, n’est pas?

When we search for how to do something, which of these do you think we generally put in the search field; “resize rows,” “resizing rows,” or “how to resize rows?” We’re not likely to enter the present participle form.

Imagine I’m driving and somehow damage a tire. I’ll probably think or even say out loud; “how do I fix a tire? Or “how to I change a tire? this is what I’d search for or perhaps speak into the search on my phone.

Writer versus User/Performer/Reader Perspective

When writing about something, the writer might think “what are the users/performers doing?” This might lead the writer to use the present participle form. Users/performers, however, might think or ask “how do I do something?” This leads to the infinitive form. It’s part of audience analysis to put yourself as the writer into the perspective of the audience.

3. The infinitive implies that we can accomplish the task and move on

Would you rather peel some potatoes or be peeling some potatoes?

Once and done or ongoing/repeating?

Finite time, not ongoing. Users want to complete a task. They want to do something. They’d rather not be completing it or doing it. The ing form implies that the task takes time, or that they may have to keep doing it, or worse, redo it. We want to do something then move on the the next task. The present participle form makes it seem as though the task may take a while to accomplish or be something difficult, or something we’ll have to keep doing over and over.

What do the buttons say?

Look at the buttons/commands in almost any application. You’ll see; Enter, Submit, Apply, Edit, Move, Copy, Confirm, Hide, Find, Go, Save, Preview, Continue, Publish, Discard Changes, Cancel, Import, Export, Backup, Select, Log in, Log out etc,. You get the point. Buttons use infinitives. Users search using infinitives. Shouldn’t your user assistance use infinitives so it matches what users do and what they look for?

I’m certainly not arguing (see…using the present participle) against present participles in all situation, just many situation in user assistance.

In addition to using the infinitive, consider using the present tense.

Unnecessary Past and Future Tense Can Cause Doubt and Confusion

Past Present Future sign postUnnecessary past, future, and other verb tenses and constructions can cause avoidable doubt and confusion on the part of your readers/listeners. When you use the past tense unnecessarily, readers may ask themselves if what you’re talking about is still relevant in the present and future. If you use the future tense unnecessarily, readers may ask themselves if this is the case now, or under what circumstances it will be the case in the future.

I’m not sure if this propensity to over-use past and future tense is due to laziness, ignorance, bad habits, or the culture (all of these). Maybe it’s a fear of the present. The past isn’t so scary, because, well, it’s in the past. The future is somewhat unknown and well, things may change, right? But why not be in the present, be in the moment? I don’t get it. Maybe we really don’t know the meaning of is.

When in doubt, technical communicators should use the tense that is the simplest, most direct, accurate, and imposes the lightest cognitive load on readers. Often times, this means using the present tense. Don’t fall for the linguistic gymnastics that you think might either; (1) make you look/sound smarter, or (2) give what you write/say some legal/grammatical wiggle room vis-a-vis reality or the truth. Our job as technical communicators is to make it easy for our readers to understand and act upon what they’re reading or hearing.

Of course there are exceptions. If your audience/purpose/context calls for lots of future and past tense, then by all means, use it.

Here are some ripped-from-common-parlance examples of what I’m talking about. Notice I didn’t write: “…what I will be talking about” or “…what I was talking about.”

“We are updating our Terms of Service.” (Microsoft site)
This begs the question, just when will you complete the process of updating your ToS, and how will I know that you updated it?

The Past is Prologue?

“I liked that house.” (HGTV Love it or List it)
When/why did you stop liking it? Home shoppers on this TV show are literally still standing in a home, or in the driveway and talking about it in the past tense. I’m dumbfounded by this.

“That house had a great backyard and master bath.” (HGTV Love it or List it)
When did it stop having a great backyard and master bath? Did someone dig up the yard since you were there? Was there a fire?

“This item was out of stock.” (email received from overseas vendor)
That’s fine. Is the item in stock now? If not, when will it be available? I’m not sure how this company stays in business with such poor sales communication!

When Does the Future Get Here?

“This course will take a minimum of 2.5 hours to complete. It does not need to be completed in one sitting.” (eLearning course intro)
Two sins here, the future tense and an inanimate object (course) with a need. My version: This course takes a minimum of 2.5 hours to complete. You do not have to complete it in one sitting.

“The purpose of this style guide is to document a consistent look and feel that will encourage consistent design, maintenance, ease of use, and navigation.” (Style Guide intro)
The future tense introduces doubt. And there’s another problem, encourage. It’s probably better to say that the guide describes consistent design for the purposes of… The guide itself is a guide. It’s management’s job to encourage/enforce it.

“Today’s how-to is going to be on replacing the serpentine belt on a 1999 F-150 5.4L V8.” (Youtube video description)
Why not say: “Here’s how to replace the serpentine belt on a 1999 F-150 5.4L V8.” It’s six words shorter and doesn’t involve the future tense. It’s a lot clearer what we’re talking about, right?

“This deal will require the approval of regulators.” (Wall Street Journal)
Is it a deal, or is it a pre-deal? Does the deal require approval now, or does something else have to happen before it requires approval? Why introduce unnecessary ambiguity?

“Your discount code will expire on August 2, 2015.” (Email from vendor)
Why not write that the code expires on August 2. Fewer words, less confusion. Less really is more.

Writing less complicated sentences using the present tense is less work for your readers/learners/doers. Isn’t that what technical communication is all about?

Consistency…or Three Chefs in the Kitchen?

WSUS ScreenshotConsistency in technical communication means that we’re consistent about grammar, construction, voice, etc, within a document, a set of materials, or an entire system. We generally refer to and follow a style guide that helps us, and our editors, keep us consistent. Software developers follow the same principle. Or at least they should.

Here’s an example where there are obviously three opinions about how to label different versions of the Microsoft Windows OS.

Windows 7 Professional and Windows XP Professional were there first. Next they added Windows 8.1, notice the decimal and one place to the right of the decimal, and the missing Professional. And most recently, they added Windows (Version 10.0). Here notice that they put Version 10.0 in parentheses and again omitted the Professional.

I find this in the recently released Microsoft Update Services 10.0.10514.0.

If I were editing this, I’d change this list to display as:

  • Windows 8.1 Pro
  • Windows 10.0 Pro
  • Windows 7 Pro
  • Windows XP Pro

Following a parallel pattern such as this makes it easier to recognize differences.

Technical Communicators Wear Many Hats

MensHatsHere are some of the jobs, titles, tasks, roles, activities…, basically the hats that I wear, as a technical communicator. Naturally, I had to put this list in alphabet order!

I wear at least a few of these on every project.

 

 

 

 

  • Authoring tool sponsor, tester, integrator, user
  • Brainstormer
  • Contractor, full time employee
  • Defect and enhancement tracker
  • Documentation Specialist
  • eLearning Developer
  • Entrepreneur
  • Friend, critic, cheerleader, co-worker, confidante
  • Graduate Student
  • Information Mapper
  • Instructional System Designer
  • Instructor, virtual instructor, trainer, teacher, mentor, resource
  • Learning Consultant
  • Learning Management System Administrator
  • Learning Technology Consultant
  • Level I/II/III technical support, triage, troubleshooter
  • Librarian, curator, archivist
  • Narrator
  • Negotiator, mediator
  • Online & context-sensitive help author
  • PHI Hider
  • Photographer, photo editor/shopper
  • Proposal Writer
  • Prospector, candidate
  • Publisher
  • Report writer, runner, editor
  • Royalty-free image purchaser
  • Screen scraper, image capturer, image editor
  • Script writer
  • SharePoint site/collection administrator
  • SME Interviewer
  • Software sponsor, installer, configurer
  • Software, document, mobile, browser, technical, and user acceptance tester
  • Sound/audio recorder, sound editor
  • Storyboarder
  • Student, learner
  • Style guide author, referee
  • Subject Matter Expert
  • Team member, team leader
  • Technical Project Manager
  • Technical Writer
  • Technology researcher, implementer
  • Template creator
  • Time tracker
  • Troubleshooter
  • User assistance creator
  • Videographer, video editor
  • Web Developer
  • Writer, author, formatter, editor, publisher

Bad Information (BI) is Everywhere and it Costs a Bundle

Bad Information Bell Curve

What is Bad Information?

Bad Information is information that isn’t quite accurate, not really helpful, or usually both. It could be a million miles off or just a few microns off. In both cases, it’s bad. That means that it isn’t good. Good Information is information we can use as-is to make, fix, do, or learn something right now. We don’t have to get a second, third, or twelfth opinion, we don’t have to balance information from 20 sources. We don’t have to research it for a year. We don’t have to deconstruct and reconstruct Good Information. Good Information is usable now. Bad information gets in the way of us discovering and acting upon the good information.

Bad Information (BI) takes many forms and wears many guises. And in fact, it’s truly everywhere. Think about it. If we were swimming in Good Information, would we have bought that item, taken that job, argued for something a certain way, or voted for that person…you get the idea. We’re neck deep in BI. Now, say it with me… “BI is everywhere!”

BI comes at us from all angles

BI comes at us like water from a fire hose. It’s sent to us in email, it’s on TV, the radio, in the news apps. Friends and family tell us BI. We get it in tweets, and on social media sites. Man! I’m still getting the Nigerian Letter for Christs’ sake.

Good Information is scarce and causes us to rely upon feelings and emotion

In addition to good/bad information, we make decisions based upon emotion and feelings. We almost have to because of the scarcity of Good Information. Take a look at ethos, pathos, and logos, if you’re not familiar. If we were (or could be) more rational and less emotional, we’d base our decisions mostly on information. That’s what I’m talking about here. One could easily argue that because there is so much BI, we’re pretty much forced to rely on emotion and gut feelings.

Some general characteristics of BI

Bad Information can have one or more of these characteristics. You can probably think of more.

  • Imprecise, inaccurate
  • Purposefully or accidentally false (the author is misleading on purpose or doesn’t know, or can’t know the truth)
  • Vague
  • Historical or forward-looking (it may have been true in the past or it might be true in the future)
  • Spin, bias, misleading
  • Omitted certain key characteristics or facts in order to support one side
  • Purely political, propaganda
  • Incomplete
  • Inconclusive
  • Shading of the truth
  • White lies, and plain old lies

Examples of BI

Since BI is everywhere, just think about your interactions with others, documentation, products, really anything. You might have had experiences such as:

  • The repair shop estimated the repairs to be around $300. They end up being $600
  • The Craigslist ad said the item is new. It’s actually five years old and smells of cigarettes
  • The piece of paper that came with the item you just bought neglects to tell you how to use the item
  • This investment is going through the roof
  • If you like your plan, you can keep your plan. Period.

Bad Information versus Business Intelligence

Business Intelligence permits businesses to grow because they have a handle on their; data, customers, product, price, profitability, market share, workforce, salaries, etc. Business Intelligence is a goal, a business plan, an ideal. And just because its initials are also BI, it should not be confused with BI, Bad Information. It’s also basically the truth described in two words instead of one. Bad Information, from a volume perspective, is the Atlantic Ocean. Business Intelligence on the other hand, is the gallon of milk in my refrigerator. The bell curve image above fairly describes the relationship between how much BI you’ll encounter versus how much truth or even truthiness.

The Cost of Bad Information

The cost of BI is astronomical. The reason that it’s so high is because so many people are so heavily invested in BI. Disseminating BI gives them the edge. From the fake Vuiton handbag salesman in NYC to the large company that doesn’t want you to know that you can buy a very similar but better product across the street. Not knowing how to use/fix/do something costs us time trying to figure it out by; trial-and-error, asking someone, Googling it, or looking for professional user assistance, etc. I’m sure you can think of many examples.

Technical Communicators Constantly Battle BI

Creating Good Information, and battling BI is our work and our passion, or at least it should be. Just as journalists should report the unbiased news, technical communicators should describe what we’re describing based upon the facts. It’s the ethical thing to do. BI is everywhere and we should keep that in mind at all times.

What is User Assistance? It’s a lot more than the Help Desk

User AssistanceUser assistance is simply something that helps users of your product or service. User assistance takes many forms. Deciding what form(s) of user assistance to create and where to publish it depends upon factors including audience, purpose, and context. Below are some examples of the types or forms of user assistance that you can produce.

 

 

Forms of User of Assistance

  • Labels, tags, stickers, warnings, symbols, inserts, etc.
  • Hard copy user guide, manual, quick start guide, Quick Reference Guide (QRG)
  • Soft copy online help, Intranet, support site, wiki
  • Release notes
  • Instructor Led Training (ILT)
  • Virtual Instructor Led Training (vILT)
  • eLearning curriculum, course, class, event, game
  • Video (not to be confused with thinly-veiled marketing materials)
  • Simulation (show me, let me try, test me)
  • Live help desk support
  • Software setup wizards
  • Social sites, moderated forums, social user assistance manager, ticket system
  • Onsite support
  • Coaching, mentoring
  • Therapy

What Mix Lord Banquo*?

Every product and service is different and therefore the mix of user assistance items that you produce and maintain is different. Prior to launching or implementing your product or service, you’ll know some of the items you’ll have to produce. However, some you will learn by experience. You’ll collect metrics of problems that users face, how they contact you, and where they expect to find help, etc. From this data, you can alter the mix of user assistance, or further develop some of what you produce.

Self Help versus Live Help

In general, live help is relatively more expensive compared to self help systems. Steering users to self help versus live help can reduce costs.

Where is the Help?

It should be exactly were your users expect it to be. When you field-tested your product or service, you probably identified areas where users might have questions or have to make decisions. This data will help you determine what types of user assistance to create, and where to place it. Have you noticed that a lot of products have toll-free telephone numbers on them. Is a live help desk the best answer for your product of service?

* Why a Shakespeare reference you ask? Stick with me here as I explain… Lord Banquo (your technical communicator and user assistance creator sidekick) was Macbeth’s (your noble product or service) ally when Macbeth faced the three witches (your customers and critics). Banquo provided calm council during this difficulty, much the same way that having expertly crafted user assistance and a user assistance plan will give you confidence. Nice huh?

Is Email your Knowledge Management System?

2009 Jed Cawthorne

(c) 2009 Jed Cawthorne

Like a lot of things, Knowledge Management (KM) can be exercised at either end of the; cost, ROI, and elaborateness spectrum. At the high end, very elaborate and costly systems can be built so that knowledge workers can share and collaborate among themselves, with the rest of the company, and with the outside world. The ideal system is a robust many-to-many system that allows for both structured and unstructured information, and that is easy to use, flexible, and secure. This ideal system manages company-maintained information ensuring its security and integrity as it is entered and edited as well as when it is consumed.

These systems function best when they are reasonably easy to use and everyone in the company buys in to it. When these systems are perceived as unreasonable and people don’t buy into it, users improvise workarounds and end up using other systems such as their email systems as their default KM systems (KMS).

Knowledge Paths

Ideally, information flows from the knowledge worker, perhaps through an editor or publisher to the Knowledge Management System (KMS). The consumer retrieves the info from the KMS. This sounds simple. Building, securing, communicating, encouraging, and enforcing such a system is another matter.

What happens in the real world is often quite a bit messier.

  1. Someone suggests that something be documented (because no one really planned for documentation at the outset)
  2. Meetings and email fly
  3. Drafts are passed around via email
  4. Someone may accidentally save a draft to SharePoint or a similar platform
  5. Document is finalized and published, perhaps to the Intranet, or SharePoint… and then forgotten about
  6. Instead of updating the document that’s published, contributors make changes to internal (non-published) copies
  7. Repeat all steps above when revisions are required

The result of this inefficient process is that bits and pieces (artifacts) of the information, and the process to create it, are spread around in peoples heads, in meeting minutes, on note paper, in email, in drafts, on shared drives, or even in collaboration platforms (mostly by accident). As you can imagine, most of this information is easy to lose.

Email KM for Everyone

An easy cheat, or workaround, to an elaborate KMS, is simply to keep your knowledge in your email system. Associates are pretty much forced to do this if they don’t have a KMS, or what they perceive as a  reasonable KMS.

They’ll also do this if  instead of publishing to a KMS, many people simply save all, or most of their email. They may move it around, categorize it, and create folders and sub-folders. But, they’re essentially just saving all of their email. When they want to know something, they search their email. This is obviously not a many-to-many scenario. Each person controls the information in his/her mail box. And can delete it.

Email KM is not efficient, but that’s what is most common in the real world.