Technical Writers’ Companion

Good user assistance is:

▪correct and unambiguous

▪written in a way that makes it easy to mentally process the given information

▪written in a way that makes it easy to act upon the given instructions

▪written in a way that makes it easy to remember the given information

Creating clear, user-friendly documents involves all levels of writing. It starts with how you organize the information within a topic. It continues with how you structure paragraphs and build sentences. It ends with the choice of words. For details about each level, see the following sections:

▪Writing in general
Summarizes the key principles that you should follow on all levels of writing.

▪Writing topics
Tells you how to organize a topic’s content, depending on the purpose of the topic.

▪Writing sections
Shows how you should organize the given information into paragraphs, how to add subheadings, and what to bear in mind when writing specific information types such as procedures or warnings.

▪Writing sentences
Shows how to build sentences that are grammatically simple, clear, and easy to understand.

▪Writing words
Shows how to choose words that add clarity rather than complexity.

▪FAQ: Spelling and punctuation
Provides a number of rules and working aids to help you with the most frequent spelling and punctuation issues.

▪FAQ: Grammar and word choice
Makes you aware of frequent grammar and word choice problems, such as the difference between the words that and which, or the correct use of the words safety and security.

▪FAQ: Standard terms and phrases
Often, you can have many names for one particular thing. To avoid confusion, you should always stick with one term. But which one is the right one? For example, should you call a program a program, or an application, or software? Do you select an option, or do you choose it? This section gives recommendations on which terms to use.