Often users refer to technical documentation when they have a problem to solve or want to know how to do something. We want to help users complete their immediate task, not overwhelm them with unnecessary information to wade through. Clear, concise text with a minimum of extra words is most helpful to users.
Guidelines and Examples
- Do not include the obvious.
Example: When writing software instructions for advanced users, ending the instructions with "Click OK [to close the dialog]" is unnecessary.
Exception: Do include "the obvious" if it is followed by something unusual, such as additional instructions or behavior that needs to be described.
- Use short sentences, simple sentence structures, and simple words. Avoid extra words.
- Instead of, "a large number of", use "many"
- Instead of "in order to" or "if you want to", use "to"
- Instead of, "If you want to make the table wider, select ...", use "Widen the table by ..."
- In online help, if there is extra information that will be useful to some users, consider putting it in an expanding or drop-down hotspot or a pop-up. Another alternative is to put the information in a separate help topic, and link to that. This will make the visible text shorter, while still providing the extra information for those to need it.
- Strive for consistency. Whenever possible, use the same words for the same thing. Resist the temptation to use synonyms to make text "more interesting" to read.
- Avoid long paragraphs. Divide long sets of instructions into shorter tasks.
Benefits of Minimalism
Writing in a minimalistic style not only more easily readable by users, it can make a huge difference to non-native speakers of your language.
Minimalism is also particularly important if the text is to be translated or localized because:
- Translators (normally non-native speakers of the source language) will find it easier to understand the text. The result will be fewer questions and a more accurate translation.
- Translation is normally paid for by the word. Fewer words result in a lower cost.
- When machine translation or computer-aided translation is used, normally partial or exact matches cost less to translate. Thus, consistency can reduce translation costs.