Creating User-Friendly Documentation

Instructions for Implementing Simplified Technical English

The Thumbs-Up Technique includes three steps for implementing Simplified Technical English:

• Step #1—Determine the relevant information and delete any irrelevant information.
• Step #2—Use the online STE Dictionary to check the approved meaning of words.
• Step #3—Modify sentences using simple, comprehensible language, according to the STE Dictionary’s suggestions.

Step #1: Determine the Relevant Information and Delete Any Irrelevant Information

Much instructional content such as task descriptions and warnings contains information that is not relevant to a user’s completing a task. In the following example, the text in italics is not relevant to clearly warning the user, while the words in bold are key information the user really needs to know.

The synthetic lubricating engine oil contains additives whose absorption can be toxic if the oil comes into prolonged contact with the skin.

Step 1 of the Thumbs-Up Technique is about removing all irrelevant information and including only information that is relevant to the user. You can distinguish those two types of information by asking yourself this question: Does the user really need this word or information to complete the task? If not, remove the words that are not pertinent.

Step #2: Use the Online STE Dictionary to Check the Approved Meaning of Words

The words you choose to use in your documentation can have a big impact. For example, the word set can mean, among other things, increase or decrease a setting, to put something down in a specific position, or describe something as fixed and rigid. Writing in a clear, concise, consistent manner is of great importance.

For example, there could be two different meanings for this example sentence: Turn off the engines not required.

1. Turn off the engines that are not required. or
2. Turning off the engines is not required.

Figure 1 shows another example of unclear text.

The need for clarity is why the ASD-STE100 Simplified Technical English Specification includes a dictionary as part 2 of the standard. While this dictionary provides a list of just 850 words whose use is permissible, its entries include both approved and unapproved words. The dictionary also defines the specific meanings of approved words that are permissible. Thus, approved words should be used only in their approved sense.

For example, the use of the verb close should be restricted to only these two meanings:

1. To operate a circuit breaker to complete an electrical circuit.
2. To move together or move to a position that stops or prevents materials from going in or out.

The word close should be used only as a verb, not as an adverb, as in the unapproved usage in this example: Do not go close to the test rig during the test.

In most cases, only one part of speech is permitted for each word. For example, the dictionary specifies the word oil is a noun. Thus, it is not permissible to use oil as a verb. Therefore, the sentence Oil the valve would not be permitted, because it uses oil as a verb. However, The oil is dirty is permissible because it uses oil as a noun.

The following four writing rules summarize the use of approved and unapproved words:

1. Choose words only from among the approved words in the dictionary.
2. Use only the approved part of speech for approved words.
3. Use only the approved meaning of each word in the STE Dictionary. Do not use any meaning that is not approved for a word.
4. Use only the forms of verbs and adjectives that the STE Dictionary approves.

You can check whether a word is approved or unapproved by using the online STE Dictionary. You’ll need to create an account to get access to the Dictionary. Once you have access, do the following to check the approved and unapproved meanings of a word in the dictionary.

1. Log in to the STE Dictionary.
2. In the Search field, type the word that you want to check—for example, ensure.
3. Click OK. In each result, the word ensure appears highlighted in green.
4. Select the approved word to use in your documentation. We’ll explain this later.

When searching the STE Dictionary for a specific keyword, all approved words appear in capital letters; those that are not approved appear in lowercase, indicating you must use another word or a different construction.

The information in the dictionary appears in four columns, as follows:

1. Keyword, or part of speech—Use an approved word only as the part of speech in this column. The use of every approved word in STE is permissible only as a specific word type. For example, ACCESS may only be a noun, not a verb, nor the adjective accessible. The STE Dictionary uses only eight parts of speech: verb (v), noun (n), pronoun (pn), article (art), adjective (adj), adverb (adv), preposition (pre), and conjunction (con).
2. Approved and alternative meanings—This column contains the meaning of an approved keyword in STE. Some English words have more than one meaning. For unapproved words, this column lists approved alternatives. If a technical name or a technical verb appears in an approved meaning, it is identified as (TN) or (TV), respectively.
3. Approved example—This column shows either how to use an approved word correctly or how to use suggested alternatives that are approved words to replace the unapproved word.
4. Example not approved—This column gives examples of text that is not in STE and uses an unapproved keyword.

Table 1 shows an excerpt from the STE Dictionary.

Let’s return to the example we used in describing Step #1. When we entered the highlighted words into the STE Dictionary, we found the approved words shown in Table 2.

Step #3: Modify Sentences Using Simple, Comprehensible Language, According to the STE Dictionary’s Suggestions

This step addresses the use of the writing rules in part 1 of the ASD-STE100 Simplified Technical English Standard. There are two things that can help you to convert sentences into STE:

1. Look at the sentences under APPROVED EXAMPLE in the STE Dictionary, which adhere to the writing rules. Even without knowing all 66 writing rules, you can copy and paste common sentences from this column or imitate their structure to create your own sentences.
2. Present the crux of the information, conveying it in simple, comprehensible language. Writing in a controlled language employs a functional approach. There are specific rules for text functions such as instructions, results, or warning messages. Here are two simple examples of functional, controlled-language rules:
   
   • Example 1:
     
     • Text function: Instruction
     • Pattern: Verb (infinitive) + article + object + punctuation mark
     • Example text: Click the button.
   • Example 2:
     
     • Text function: Result
     • Pattern: Article + object + verb (present tense) + punctuation mark.
     • Example text: The Expense Report window appears.

Both examples present the crux of the information, conveying it in simple, comprehensible language. Keep this in mind when modifying your sentences to adhere to STE.

Let’s again go back to the example from step #1. We’ve modified the text, as follows:

Do not get the engine oil on your skin. The oil is poisonous. It can go through your skin and into your body.

As you can see, we’ve used fewer words than were in the original text.

Instructions for Implementing Minimalism

The Thumbs-Up Technique includes four steps for implementing minimalism—one step for each principle of minimalism.

Step #1: Choose an Action-Oriented Approach

Because minimalism’s aim is to provide users with an immediate opportunity for meaningful action, minimal instructions are always action oriented. In a minimalist approach, the assumption is that users don’t want to lose time going through information that does not help them to perform a task. Therefore, the minimalist information designer gives the user less to read, but more to do.

Minimalism also requires respect for the integrity of the user’s activity. Information designers should not tell users what they already know or interrupt them with unnecessary information or descriptions. [2] Users are interested in reaching an objective, not in learning about trivial information that could distract them from their task.

Less content is fine, but how do we ensure the remaining text is valuable to the user? By focusing on actions! This is where STE and minimalism meet. Focusing on actions requires you to select terminology that reflects the task the user must accomplish to reach his objective. Using action verbs ensures the content fits the user’s intention. Therefore, during the design process, the author should always ask: What does the user want to do with this product? This method is an excellent guide for designing an action-oriented topic and skipping all useless product description.

To determine what kind of action verbs to use, we recommend that you start with an inquiry about the user’s terminology. Existing terminology databases, style guides, and standardized terms and phrases such as those in the STE Dictionary and the writing rules are extremely helpful in making terminology decisions. You can include such databases in a design project from the beginning to help you create meaningful subheadings for procedures.

To help users quickly understand how to solve a problem or perform a task, it is essential that you provide not only meaningful, but also unvarying terminology. Once a user has grasped what phrases such as download the file and upload the file mean, saying load a file could be confusing. So it’s very important to follow the STE rules.

To implement the first principle of minimalism:

1. Delete all unnecessary information from your documentation, including such sections as General Information, Introduction, and About.
2. Skip the information the user already knows—for example, a lineman already knows that electricity is dangerous.
3. Write action- and task-oriented descriptions by doing the following:
   
   • Use terminology databases that fit the user— vocabulary—such as the STE database.
   • Use action verbs.
   • Write meaningful headings for procedures.

Example:

These following instructions adhere to the first principle of minimalism:

Step #2: Anchor Instructions in the Domain

Anchoring instructions in the domain means writing about the product—a software application, machine, or device—should not be the objective in itself. The product is merely a means—almost never an end in itself. [2]

The primary error of non-minimalist documentation is describing the user interface or the device itself. Describing what is in front of the user is redundant information. In contrast, crafting user-centered procedures—instead of descriptions—that build on users’ prior skills, knowledge, and experience, which are familiar to them is highly effective. [2]

Therefore, minimalist information developers focus on labeling tasks using the users’ own words. Generally, you can acquire this terminology from users during their initial training, ensuring it is anchored in their basic know-how. To maximize users’ quick, unambiguous understanding of tasks, it is essential that you use terms that are familiar to them.

To implement the second principle of minimalism:

1. Analyze your users’ work environment, including their skills, knowledge, and experience.
2. Stick to task and user terminology.
3. Don’t describe the tool—for example, the user interface or device.

Examples:

This first example describes a user interface, so does not adhere to the second principle of minimalism:

The following example adheres to the second principle of minimalism:

Step #3: Support Error Recognition and Recovery

Because users do make mistakes while performing tasks, experts in minimalism recommend that troubleshooting information predominate in operating or maintenance manuals. The main rule here is first to help users avoid making mistakes by communicating in short, simple sentences; clearly indicating action information; and minimizing jargon. [1] STE and minimalism both support this goal.

Furthermore, to master error handling, experts in minimalism recommend that you aid detection by helping users recognize there is an error, then aid diagnosis and recovery by helping them to understand what has happened, so they can diagnose the problem and figure out how to recover from it.

For effective detection, the labeling of the error is crucial. The label should be precise and meaningful. To write effective error messages, stick to the users’ terms. Once again, limiting the vocabulary to the terms users have already learned or agreed upon guarantees a high level of immediate comprehension.

To implement the third principle of minimalism:

1. Add troubleshooting information to the tasks.
2. Make troubleshooting sections recognizable by adding a precise title and using terminology that is used by or familiar to users.
3. Structure your troubleshooting information, as follows: title, detection, cause or diagnosis, and remedy.

Examples:

In the following example, the troubleshooting information is not clearly called out. Thus, this example does not adhere to the third principle of minimalism.

The following troubleshooting example follows the third principle of minimalism:

Step #4: Support Successful Information Access

Users do not generally read a manual from cover to cover. Instead, they open the manual only when they encounter a problem. So their main task is locating the solution to their problem.

Searching through a 576-page manual for a three-sentence answer is often very painful. Searching a PDF can be extremely frustrating because the system does not take synonyms into account. It supports only binary decisions—for example, Does this term exist in this file? [YES] or [NO].

To overcome this issue, information developers should stick to using well-defined terminology and develop a meaningful table of contents and index. The chapter titles and section headings that appear in a table of contents should be action oriented and designed with STE rules in mind. Because indexes list not only meaningful terms in a manual, but also their synonyms, they are effective in helping users to find the right information in a minimal amount of time.

To implement the fourth principle of minimalism:

1. Create meaningful titles.
2. Design a table of contents.
3. Design a detailed index.
4. Add synonyms to the index.

Conclusion

In this article, we’ve provided detailed steps for implementing Simplified Technical English and minimalism in your product documentation, using the Thumbs-Up Technique. As we’ve demonstrated, applying the principles of Simplified Technical English and minimalism can greatly improve the consistency and usability of any type of documentation. 

Endnotes

[1] Carroll, John M., and Hans van der Meij. “Ten Misconceptions about Minimalism,” in Minimalism Beyond the Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill. Boston: MIT Press, 1990.

[2] van der Meij, Hans, and John M. Carroll. “Principles and Heuristics for Designing Minimalist Instruction,” in Minimalism Beyond the Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill. Boston: MIT Press, 1990.

Reference

Martin, Lindsay. “Technology Management and Content Development Trends.” CIDM Best Practices, April 2016.