Documentation - Mar 16, 2022

Here's why consistency in your documentation and training matters

"When story and behavior are consistent, we relax; when story and behavior are inconsistent, we get tense. We have a deep psychological need for our stories and behaviors to be consistent." ― Christina Baldwin, Storycatcher: Making Sense of Our Lives through the Power and Practice of Story


As an editor, one of my main tasks is to impose consistency on the writing I edit. Many of the changes I make are about maintaining consistency in styles, in lists and headings, and in the way things are formulated.

But why should we strive for consistency in our documentation and training?

Consistency is important because it helps comprehension. Having clear rules about consistency makes the task of writing easier (you have a solution worked out for all occurrences of a problem each time you face it), and these rules make your writing more professional. Readers assume that all inconsistencies are intentional, so consistency gives your readers confidence in your writing.

Distractions

When reading, most people, notice many things subconsciously. Every time we introduce an inconsistency, it makes the reader stop up and wonder if it was intentional or a mistake. This slows the act of reading and comprehension.

Capitalization 

In English, we use capitalization to indicate the start of a sentence or the name of something. If we change a capitalized form to a lowercase form, the reader won’t know if the document is talking about the same entity or referring to something in general. This creates confusion.

Numbers

Words and numerals are two distinct abstract concepts. When we mix numerals with words, it makes it harder to read, because the brain has to translate two different types of symbols. Therefore, if we use symbols consistently, we're helping the reader.

Hyphenation

Hyphens in compound words help to clarify meaning. The hyphen signals that the two words belong together as a single unit. If you then deviate from this form, the reader will assume that you mean something different than before.

Word choice

If you have two words for the same thing, the reader will assume (quite rightly) that you are talking about two different things. This is particularly important in work instructions or technical content where the subject matter is complex.

Formatting

Apart from being a distraction, inconsistent formatting can cause confusion. Consistency of formatting simplifies navigating through the document and makes the result look professional. Readers do notice differences in the use of style and formatting.

When we remove inconsistency from our text, we also remove the barrier between our readers and their understanding of it. We ensure that our writing conveys the message that we intended. So when we write or edit with consistency in mind, we are making it easier for our readers to understand our writing by teaching them what to expect, and we are also removing the obstacles that make understanding difficult.