The process of simplifying text

The starting level within a document is the chapter. In structured technical documentation, a chapter is typically a single DITA module: an individual unit that has a title and content.

The purpose of a chapter is to provide a block of information on a certain topic. Thus, you should make sure that one chapter only deals with one topic and has a logical information flow.

A chapter should only contain the necessary content. Only tell the reader what they need to know, not what you think it would be nice or fun to know.

Chapters are always headed by titles. In documents, titles typically comprise the table of contents or the bookmarks panel of a PDF document. When users seek information, the titles of chapters are likely the first things they encounter and pay attention to because titles anticipate the content of sections. Therefore, it is important to make sure the title of the chapter matches its content.

In technical documentation, a paragraph can be as short as one clause or consist of several sentences. However, prose is the only genre where the reader is allowed to encounter long sections of text with no paragraph breaks, or walls of text.

Walls of text are exhausting to read, and the mere sight of them can deter readers and discourage engaging with the content. A good rule of thumb is that if you, the writer, don’t feel like reading a paragraph due to its length, your readers will not want to either.

The simplest method to deconstruct a wall of text is by adding paragraph breaks. Chopping up massive chunks of text into bite-sized pieces makes the document appear more approachable. It also facilitates skimming, which can aid information seeking.

Whereas simply adding some paragraph breaks may make documentation more readable and approachable, it’s even better to consider alternative means of presentation. This means that whenever you can, you should present content either as a list or table. Lists and tables further increase the approachability and readability of documentation as they are easy to spot, easy to skim, and quick to read. This is especially true if the list items are long.

Another concern as regards paragraphs is the relevance of their contents. One paragraph should only discuss one specific issue or one aspect of a specific issue.

Additionally, you should remove any repetitive or irrelevant sentences from the text. When a single document is edited or added to by several authors, same things may end up being said more than once. This adds unnecessary length to a text and can be confusing or frustrating to read.

Similarly to paragraphs, sentences should not be overly long. If a sentence is very long, the reader will have forgotten where it began once they reach the end. As a result, the reader has to read the sentence several times, which reduces the efficiency of the text.

The STE recommends that sentences in English technical documentation be no longer than 25 words. Whereas the act of counting the words in a sentence can occasionally be helpful, it is better to focus on the content and message of the sentence. If you absolutely cannot shorten a sentence without altering or losing its meaning, just leave it! An occasional 30-word sentence is not detrimental to the text as long as they don’t become the norm.

In order to shorten long sentences, you can:

• Format lists of items into bullet point lists, like I'm doing here!
• Remove all unnecessary words as long as the sentence retains its meaning.
• Separate the clauses that make up the sentences and join them together with transitional words or repetition.
• Rephrase long expressions into shorter ones.

Another way to make sentences more readable is to focus on the order in which information is presented. New information is typically placed towards the end of a sentence. This way, the reader can continue to build up on the things she already knows.

The editing of clauses shares some similarities with the editing of sentences, such as aiming to keep them short and placing new information at the end of a clause. You don't need to edit sentences and clauses separately, but for clarity, I discuss them separately here.

In my view, the editing of clauses focuses primarily on their syntactic properties, such as:

• The qualities of noun phrases (NPs).
• The use of the active voice.
• Word order.
• Subject-verb agreement.

As regards NPs, the property to focus on is their length. According to the STE, NPs should not be longer than three words; the longer the NP in a clause is, the more difficult the clause is to understand. Try to omit any unnecessary modifiers or rephrase the clause so that you don’t have to use a long NP.

Another aspect which improves readability is the use of the active voice. The active voice is preferable to the passive voice because the subject constituent of the clause (the agent) is transparent. Thus, there is no question of who or what the subject is, which reduces ambiguity. The reader doesn’t have to guess who does what, which is a particularly relevant quality in an operative text.

Additionally, clauses should have the typical English word order of subject-verb-object (SVO), which is often achieved by using the active voice. Using the proper word order helps produce clauses that are understandable, meaningful, and grammatically correct.

Finally, you should make sure that in each clause, the subject constituent agrees grammatically with the predicate verb. In simple terms, this means that if the subject is in plural form, the verb is also in plural form. Especially in the case of very long NPs, the proper form of the verb may be difficult to determine, which is another reason for opting for short subject NPs!

The final level of text in the top-to-bottom approach is the word. As regards word choices, you should refer to an appropriate style guide, be it the STE specification or a company-specific style guide. Consulting the style guide in your company is the best way to ensure you're using appropriate terms.

Some general pointers for word choices include using:

• Words and expressions that are common and familiar.
• Words that are unambiguous in the given context.
• Verbs instead of nominalised forms.

Firstly, one should use words that are common and therefore more likely familiar to the reader. The STE or company-internal term banks are great tools for checking which words to use.

It is also important to avoid unnecessary occupational jargon. Always keep in mind who your readers are! User documentation is typically not intended for subject matter experts to use. Instead, the user group may include people who are unfamiliar with the specialised language of the field you're writing in. Users do not want nor should they need to spend time making sense of the content. It is the technical writer’s responsibility to take readers into account and produce language that is appropriate for their assumed level of expertise.

Sometimes, however, it may be difficult to distinguish jargon from terms that are common, field-specific yet complex-looking. In such cases, it can be useful to ask for advice from a colleague or an SME. Sometimes a simple Google query can reveal whether the word is commonly used when discussing the subject matter in question. You should, however, first and foremost try to determine whether the term is comprehensible to the readers.

Additionally, the words and terms in documentation should be ones that have the least ambiguity in the surrounding context. Because the primary function of operative texts is to instruct readers to do something, the words should be as clear and transparent as possible.

The final point is to use verbs instead of nominalisations. Nominalisations are words that are not nouns but are used as nouns, such as to nominalise → nominalisation or to operate → operating. Avoiding nominalisations is not always easy or even possible, but a useful guideline is to replace them with verbs whenever possible.