Tone
Inappropriate tone can hinder reader access to information. A neutral tone free of opinion or personal flavor reduces the processing load for the reader to understand the information. Another benefit of a neutral tone is that several writers can work in parallel on a large technical documentation project. Furthermore, different writers can join the project at different times. The use of a neutral tone helps to achieve consistency across a documentation set, and thereby facilitates user access to information. The best way to achieve a common, neutral tone is to apply the following principles:
- Avoid humor
-
Humor distracts from the information you are trying to provide. Humor also makes documentation difficult to translate. Stay factual.
- Avoid personal opinions
-
Whether you think a function is useful or woeful is irrelevant. Report the function to the user, with instructions about how to use the function. Stay accurate.
- Avoid colloquial language
-
Colloquial language is difficult to translate and usually culture-specific. Stay neutral.
- Avoid topical expressions
-
An expression that is in common use today might convey something completely different tomorrow. Stay technical.
- Avoid aspirational statements
-
Statements about the future developments of a product do not belong in technical documentation. Write about what you see right now. Stay real.