Tricky Grammar in User Guides

All technical writers are famous for being meticulous about grammar, style, and punctuation. Reviewers and editors are even more scrupulous. If we count the time wasted on checking grammar in user guides, it will probably drive us to the conclusion that this is one of the most important parts of the process. Wait, what?… Did I just say ‘time wasted on checking grammar’? I did, yes. Well, you see, technically, the main aim of technical writing is to deliver a clear message to their audience, not just produce grammatically correct technical texts. Let me explain further how proofreading can become a time-devouring monster that will interfere with your best-laid help authoring plans. And, hopefully, at the end of this blog, you will learn how to fight it.

They say we live in a focus-based universe. I find it hard to argue with that. Creating a tech writing project can be a great example here – while you are focusing on how grammatically correct things are, you are forgetting about other crucial things, letting them slip away. You are too focused on smaller stuff to see the bigger picture. This is why grammar should not be placed on a pedestal of technical writing.

I bet you know a lot of grammar and punctuation rules and this is awesome. And, I am sure that you are still learning or revising things. Especially when you are creating technical texts not in your mother tongue. But try thinking about all the times when you put the writing process on hold to get a very specific grammar rule from Google and that took you more time than you are ready to admit. Sometimes, procrastination is to blame – who doesn’t like googling ‘important things’ when they actually have a help topic to write. But, there’s one more possible reason for this behavior – inability to evaluate how important a grammar rule is. This might sound blasphemous, but hear me out.

Putting Grammar and Punctuation Rules to the Test

All grammar and punctuation rules can be broken down into two categories: essential and non-essential. If you accept this concept, you will see that some rules are not worth worrying about. How do you differentiate? We can’t take every single grammar rule and just put it into two columns for reference. So, we’ll need to get creative. Here are some things that point to the fact that a rule is essential:

• Information in a sentence gets ambiguous. Technical texts should be able to convey a straightforward message, any ambiguity, any chance that a sentence can have more than one meaning to it, is a clear indication that a serious mistake took place.
• Information in a sentence is vague and unclear. If the first point can mislead a reader, this one will leave them confused. And, instead of case deflection through technical documentation, you will have frustrated users calling support.
• Your gut is telling you something is off. When you work a lot with texts and you’ve studied grammar thoroughly, you just develop a hunch when it comes to mistakes. Trust this feeling.

Non-essential rules are the opposite of everything mentioned earlier – they do not distort the message and are often just acceptable variations of one thing. A couple of examples to explain what I mean:

• Articles. Articles can be safely omitted in titles, everyone knows that. But if you take a look at technical documentation, you will often see articles omitted in other places too, like brief ‘what’s new’ descriptions in software manuals. Is this a mistake? Not really. These are like mini-titles. Fewer words in this example means faster getting the info across.
• Prepositions. In many cases, several prepositions can be used with the same word, and the difference there will be that one is used less often, or refers to a certain type of English, like U.S. English. Or, a shift in meaning is barely noticeable like:

  There’s some truth in it.

  There’s some truth to it.

  Both mean that something is partially true. If you dig deeper, you might find out that there’s a slight difference which wouldn’t really matter if you decided to use either of the prepositions in your text.

• This can apply to using tenses, too. Present Simple instead and Present Perfect, for example, can be interchangeable. If no confusion is caused by using one tense form and not the other, it is OK.

Conclusion

Now that we got rid of this grammar craze and freed up some precious time, it should be put to good use. We’ve focused enough on details – it is the right moment to take a step back and see the whole picture. Use this opportunity to make sure you are on track with the bigger goals!

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices