It's better to be clear than correct
English writing has a lot of rules, but good technical writers know when to follow them and when to break them. Here are a few examples of when it's better to be clear than correct.
English has rules. A lot of rules. Some of them make no sense if you grew up with another language. Some of them make no sense if you grew up with English. Even though technically correct is the best kind of correct, it’s better to be understood than to strictly follow grammatical rules.
This does not mean you can be factually incorrect in what you write. It’s best to have all your facts right, even though some points may be less important than others. This means strict adherence to the grammar you were taught in school. Your prose is not code; it will not fail because you forgot a semicolon.
Ultimately, the choice to break a rule is just that: a choice. Grammar rules are not laws, they’re conventions. Don’t let them get in the way of being understood. Does ending a sentence with a preposition sound better than rewording it to avoid the bane of your sophomore English teacher? Then find a good preposition to end your sentence with! A stiff, overly-formal writing style can put off your reader. Don’t let the means of your message get in the way of the meaning.
URLs in sentences
One example of breaking the rules is when you need to include a URL in a sentence. Often, you can make it a hyperlink. Problem solved! But if it’s a plain text format, then what do you do? If you put the period at the end, you end up with something like “Read more at https://example.com/info.” That could result in someone trying to type the period in the URL, which will not work.
If the URL is at the end of the line, just leave the period off! If there’s another sentence following, you can put a space before the period or add several extra spaces.
Of course, you might choose to add a reference instead and include the link at the bottom of the text. This is probably easier to read in most cases. When you choose to break a rule, that is a flag to prompt you to review what you wrote. Can you rewrite it to make it more clear?
Who does what
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.
The lack of an actor is the clearest sign that you’re not being clear. For example, a security policy needs to be very 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 sometimes it's okay to use some passive voice for rhetorical flourish.
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.
Don’t worry if this sounds difficult. Generations of English teachers have labored to drive the passive voice out of us with limited success. And there are tools that can help if you can’t catch these issues in your own work. For example, the Yoast SEO plugin for WordPress does a fine job of highlighting passive voice. You can find other grammar tools online, both free and paid-for.
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 is to have someone else make the diagram from what you’ve written. There’s nothing like a second pair of eyes.