Rules for more intelligible texts in technical documentation
An optimum text intelligibility in technical documentation is more important than in almost every other type of text. To achieve that, the linguistic style of the texts and a well-conceived structure are critical. Ten tips help you to optimize text intelligibility and increase usability.
Checklist for the daily editorial routine:
- Linguistic correctness and simplicity
It is essential to eliminate linguistic errors as far as possible. Another key criterion for intelligible text is choosing the appropriate style of language. This includes: short and well-known words; specific words which trigger vivid connotations; simple sentences containing no more than one main clause and one subordinate clause; active sentences rather than passive sentences. - From the known to the unknown
User are supposed to learn new, currently unknown correlations. To make that easier, technical documentation first establishes the exisiting knowledge and then follows up with new information. Based on that foundation, new facts are more intelligible. - From the rule to the exception
If the users get to know the normal case first, it is easier for them to recognize exceptions and classify them correctly. The other way round would be rather confusing. - From the problem to the solution
If users get presented with a solution without knowing to which problem it refers, they will not be able to classify or apply new knowledge. If the problem is brought forward afterwards, they will usually have to read the solution again, because only now they will be able to understand. - First the positive, then the negative statement
A positive characterization is much more memorable and intelligible than a negative one. That is why users should first get to learn, what a product is able to do, then, what it is not able to do. - Advance organizers
These are short introductions preceding the actual text. They shall provide the users with an overview of the subject matter. They are very suitable for complex issues which contain a great amount of new information and therefore present intellectual challenges in terms of intelligibility. - Careful emphasizing
The use of bold or italic font can help users to comprehend text: they can skim over the text, scanning it for information and filtering it according to relevance. However, emphases should be used economically and according to consistent rules. Otherwise, they can become confusing. - Headings and marginal notes
Similarly, headings and marginal notes help readers to navigate in the text and draw them to the information they are looking for. To improve text intelligibility, they should summarize the substance of the section of the text. - Visualizing with graphics
Screenshots, i llustrations, photographs, diagrams or pictograms are an outstanding means to increase text intelligibility. If they are well-conceived and are used efficiently, the text and the illustrations can be mutually supportive. - Mark information classes
Users need to realize at any time, which kind of information they are dealing with. Structural and graphical means can make this clear: For example, step-by-step instructions should always be written in numbered lists, safety notes should always be marked with colored symbols.
These rules contribute decisively to create intelligible texts from scratch, but also to substantially optimize the intelligibility of existing texts.