By Marcia Riefer Johnston on Writing docs from July 20, 2023
Linus Says: We are excited to share this guest blog post by Marcia Riefer Johnston. We love the Write the Docs community and all the wonderful connections that grow from it. This article grew out of an unselected lightning talk that turned into an unconference session that Marcia led at the Write the Docs Conference in Portland in May. Thank you to Marcia for sharing her ideas in the WTD Slack and planting the seeds of connection that grew into this delightful post!
Your business puts the customer first. Every business makes this claim, of course. But does your company's content—product documentation, blog posts, newsletters, wiki pages, emails, you name it—reflect that commitment? Do your company's writers (that includes everyone) know how to put the customer first in their sentences?
Before we get down to sentence-level tactics, let's step back and consider the impact of choosing your point of view, in general, in your communication. Take these two photos. The content is the same: a couple of kids playing with blocks. The point of view couldn't be less the same, though. The subject—what the photo is about—is not the same. One photo is about blocks—your company’s blocks, let’s say. The other is about kids—your potential customers’ kids.
How do you identify the subject in each photo? As the viewer, you don’t have to give this question a thought; you just know. Toys here, kids there. The photographer thought about it, though. A skilled photographer uses framing, color, camera angle, focal point—the elements of visual grammar—to convey what's important.
A skilled writer does the same thing using the elements of language grammar.
Whatever you write for your business, unless you have a reason to do otherwise (for example, if you’re writing specifications), make people your grammatical subject. Consider this type of sentence:
Our gizmo enables customers to do this cool thing.
This product-first structure is so common that you may not think twice about it. Of course you want people to know what your product does. Here’s the thing. Customers want to know not what your product can do for them but what they can do with your product.
To make that shift in your writing, start noticing product-centric sentences. The moment you notice the product in the lead, opportunity jumps out at you. Sentences practically rewrite themselves.
Take the example sentence. The moment you notice that the subject (gizmo) is a product, the sentence begs you to move the words around, something like what’s shown in Figure 1.
The original sentence talks about the gizmo. The revised sentence talks about the customer. Same content, different subjects. Different reader experiences.
I have a suggestion to help you notice product-centric writing: develop an eye for these three words: enable, let, and allow. Look back at Figure 1, for example. The original gizmo sentence uses the verb enable. Here's a sentence that uses let:
Tags let you categorize resources by environment.
How might you revise that sentence to put the customer first? Start by deleting let. Then bump the you to the front. Alternatively, lead with use, an imperative verb, which, by definition, has the implied subject you. Figure 2 shows both possible revisions.
The following example uses allow:
A logical name allows you to refer to a resource in the template.
In this case, after deleting allows, you might make you the subject in a number of ways. Figure 3 shows some options.
As shown in the last bullet in Figure 3, putting a person first grammatically—making a person your subject—doesn’t necessarily mean putting the person first in the sentence. See Dick run. See Jane run. See the customer do cool things with your product. Who wants to read sentence after sentence like that?
Enter the flexibility of the English language. You can slide words around without changing a sentence’s underlying structure. Take a look at the two sentences in Figure 4. Both have the same subject: you. In one case, it comes at the beginning. In the other, it comes in the middle. Basically, the prepositional phrase has scooched from one end to the other. Either way, you would diagram the sentence the same way. The subject always comes first grammatically. That’s the kind of first I’m talking about.
Hold on, you might be thinking. Back up to those three tipoff words: enable, let, and allow. They’re legit. Nothing wrong with them. Look them up in any dictionary.
Right you are. I’m cautioning only against enabling people to do something, allowing people to do something, or letting people do something. If your company has a style guide, chances are it suggests avoiding this type of usage.
Enable a product feature? No problem. Let something happen? No problem. You might even allow someone access to something; allow makes sense for people when you're talking about permission, as shown in Figure 5.
In short, enable, let, and allow aren't dirty words. Let them catch your eye, and then decide whether to keep them. (If you saw what I did there, you're on your way.)
Passive voice may also tip you off to sentences that put the customer somewhere other than first. Take this sentence:
These accounts can be transferred to your organization.
How do you know that be transferred is passive voice? If you're a language geek, you analyze the verb structure: be-verb (is) + past participle (transferred).1 Boom. Passive voice.
Alternatively, add by zombies.
These accounts can be transferred to your organization by zombies.
If you can you picture zombies doing the thing, you're looking at passive voice. (Credit for the by-zombies test appears to go to Dr. Rebecca Johnson, who tweeted the idea in 2012.)
Before you can edit a passive-voice sentence, you might have to do some sleuthing. Passive voice notoriously hides who or what is doing the thing (transferring the accounts, in this case). Here’s one possible edit, which is also shown in Figure 6:
You can transfer these accounts to your organization.
You don’t have to convert all passive voice to active. Sometimes the subject needs to be obscured. I mean, sometimes you need to obscure the subject.
Do you compose your sentences with the care of a photographer composing an image? That's what it takes to put your customer first in your sentences. For starters, look for allow, enable, let, and passive-voice verbs. Remember that people don’t care what your products can do. They care about what they can do with your products.
1 English has eight be-verbs: am, is, are, was, were, be, being, been. Pay attention to them, and you strengthen your writing in all kinds of ways. To find out how, see my blog post Be and Me, which kicks off with a video of the not-to-be-missed Be-Verb Song courtesy of Benjamin Kjos, who sang it for me after attending my workshop at Confab 2015.
General posts useful to all documentarians about writing documentation, editing and publishing workflows, and more.
Your flight plan for how to get the most out of KnowledgeOwl features and integrate them into your workflows.
Major KnowledgeOwl company announcements.
Learn how others are using KnowledgeOwl & get pro tips on how to make the most of KO!
Find out more about who we are and what we value.
We believe good support is the foundation of good business. Learn about support tools and methodology.
Learn more about tools to solve various documentarian issues, within and beyond KnowledgeOwl.
Not sure what category you need? Browse all the posts on our blog.
Watch a 5-minute video and schedule time to speak with one of our owls.