Consistency in Block-Based Documentation

Blog post from Nov 28, 2017

For diverse reasons, many enterprises write documentation with the help of topics or building blocks. This represents a formidable challenge for authors, as even minor inconsistencies can make the entire building, i.e. the document, falter if the individual building blocks do not neatly fit together.

Consistency – a Prerequisite for Healthy Building Blocks

A text is consistent if it follows the same language, style, and content rules and standards. Failure to do so would result in building blocks that cannot be seamlessly combined with other building blocks.

Language

For example, inconsistent language can arise by mixing different spelling conventions (e.g. "reinsert" vs. "re-insert"). Moreover, spelling errors and misuse of words (e.g. "complementary" and "complimentary") can result in inconsistent language that readers stumble over. Readers might think that the text has been composed by different authors. However, such lines of thinking are not conducive to understanding content. 

Style

Writing styles are as unique as snowflakes. No two persons have exactly the same style. In technical text, for example, it might be possible to say either "Press button to open door" or "Press the button to open the door". When building blocks of two authors are later joined, such style variations become evident and irritate the reader. This can baffle the reader or result in his attributing different levels of importance to various instructions.

Content

There are dozens of ways in which an idea can be expressed with different words or sentences. Though such freedom of wording may seem impressive, the associated review and translation overhead makes such variants a cost trap for the technical documentation department. And again, the reader is the one who suffers most, as he constantly needs to make a mental note of which words actually have the same meaning. He thus needs to re-evaluate and grasp instructions that are written differently. This is a cumbersome and error-prone process.

How Can High Consistency Be Ensured?

Enterprises create and maintain editorial guides and terminology databases in order to increase the consistency of their building blocks. However, it would not be very helpful to simply provide the author with these resources and expect him to apply them. The author would not have the time to memorize the editorial guide or to check the terminology list every time he wants to use a new word. After all, he has deadlines to meet. The situation is very similar for the reviewer. An author assistance tool is needed in order to ensure that building blocks are consistently written with the help of the editorial guide and the term database.

For further information, refer to the white paper "Topic-Oriented Documentation or How I Fell in Love with the Building Block".

tl;dr

Consistency is very important for block-based content. An author assistance tool helps you to ensure textual consistency.