Be clear about who does what

A fountain pen writing with black ink on ruled notebook paper.

This post is part of a writing advice series. Writing clearly is one of the most important — and overlooked — skills.

One of the big mistakes I see when writing policies is a lack of clarity about who performs specific actions. This can be a problem in other forms of writing, too, but it’s most harmful for policies and procedures. If you’re not clear about who is supposed to act, people will assume that it’s not them.

Include an actor

The lack of an actor is the clearest sign that you’re not being clear. “A list of inactive accounts is created” doesn’t say who you expect to create the list. Instead, you can say “the Security Officer creates a list of inactive accounts.” Now everyone understands who does the work.

You could also write “A list of inactive accounts is created by the Security Officer,” but that’s unnecessarily complex. In general, you should stick with “subject-verb-object” construction, particularly when writing instructions or procedures. But you can have some passive voice for rhetorical flourish, as a treat. The last sentence of the first paragraph is a good example.

The other key part of clarity is separating the actor from the tool. In other words, the account activity checker script doesn’t create a list of inactive accounts; the Security Officer uses the account activity checker script to create a list of inactive accounts. Don’t transfer responsibility from people to machines inappropriately. Unless the action runs automatically based on a timer or an external trigger, the actor is a person.

Catch yourself

If this sounds difficult, don’t worry. First of all, generations of English teachers have labored to drive the passive voice out of us with limited success. Second, there are tools that can help if you can’t catch these issues in your own work. The Yoast SEO plugin for WordPress does a fine job of highlighting passive voice. In fact, it is angry with me right now because this post contains more passive voice than it thinks is ideal. You can find other grammar tools, both free and paid online.

You can also draw a swimlane diagram to help. If you can immediately tell which lane an action belongs in, you’re probably clear about who the actor is. If you have to think about it, you haven’t written it clearly. Even better, though, is to have someone else make the diagram from what you’ve written. There’s nothing like a second pair of eyes.

A note on apologies

I said a lack of clarity is most harmful when writing policies and procedures, but there’s another important case: apologies. If you’re doing anything meaningful in this life, you’ll have to apologize from time to time. That’s the nature of humanity: we make mistakes. You may feel a temptation to use passive voice when writing an apology. That shifts the blame — or at least the reader’s perception of blame — away from you. Who wants to be blamed?

But leadership means holding yourself accountable for your mistakes. Don’t say “important steps in the process were skipped.” Say “I skipped important steps in the process.” I know it feels bad, but it helps you build credibility with your community.

This post’s featured photo by Aaron Burden on Unsplash.

Ben formerly led open source messaging at Docker and was the Fedora Program Manager. He is the author of Program Management for Open Source Projects. Ben is an Open Organization Ambassador and frequent conference speaker. His personal website is Funnel Fiasco.


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.