Top

Creating User-Friendly Documentation

August 8, 2016

Simplified Technical English (STE) and minimalism are of great importance in writing user-friendly documentation, particularly for user content such as maintenance manuals. However, many technical writers experience specific problems when implementing STE and minimalism. The ASD-STE100 Specification is a complex document, and a disadvantage of this approach is its expensive learning time. Plus, literature about minimalism comprises complex documents, and training is scarce.

In this article, we’ll clearly describe the steps you need to take to implement the principles of Simplified Technical English and minimalism in designing optimized, user-friendly documentation. First, we’ll cover the concepts behind the Thumbs-Up Technique—principally, STE and minimalism. Next, we’ll detail the steps to follow in implementing STE. Finally, we’ll detail the steps to follow in implementing minimalism. By following the steps we’ll outline, you can apply the principles of STE and minimalism to your documentation quite easily.

Champion Advertisement
Continue Reading…

Concepts Behind the Thumbs-Up Technique

An updated Thumbs-Up Technique a good first step in improving the quality of content by implementing both Simplified Technical English and minimalism, decreasing translations costs, and creating a better user experience. The Thumbs-Up Technique is based on the ASD-STE100 Specification. The key concepts behind the Thumbs-Up Technique are Simplified Technical English and minimalism.

The Concepts of Simplified Technical English

English is a very rich language and is the language most used in writing technical documentation. However, many words can be redundant or ambiguous, and English grammar is complex. Often, English is not the native language of the readers of technical documentation such as user manuals and safety instructions. In fact, many readers have a limited knowledge of English, and they are easily confused by complex sentence structures and the different meanings and synonyms of English words.

The Aerospace and Defence Industries Association of Europe (ASD) developed Simplified Technical English to help the users of English-language documentation to understand what they read—particularly those participating in multinational programs. They created the ASD-STE100 Simplified Technical English Specification, which comprises two parts: STE Writing Rules and the STE Dictionary. The Thumbs-Up Technique includes simplified versions of both parts of this specification. Using Simplified Technical English is all about writing clear, unambiguous content by employing the Thumbs-Up Technique’s writing rules and dictionary.

The Concepts Behind Minimalism

Minimalism in technical communication is a user-centered design philosophy. The priority of a minimalistic approach to documentation is to support the usage of a product by providing only the information people really need to perform a certain task. Another goal of minimalism is to adapt to the audience as much as possible.

Confusing minimalism with brevity is a misconception about this approach. Wantonly slashing text without changing other design characteristics does not lead to a minimalist design solution. [1]

Four principles are the foundation of minimalism:

  1. Choose an action-oriented approach.
  2. Anchor the tool in the task domain.
  3. Support error recognition and recovery.
  4. Support reading to do, study, and locate.

The Thumbs-Up Technique demonstrates how to implement these four key principles of minimalism. Next, we’ll break this technique down into actionable steps.

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.

Figure 1—What might the sentence Cut the power mean?
What might the sentence Cut the power mean?

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.

Table 1—An excerpt from the STE Dictionary
Keyword, or Part of Speech Approved and Alternative Meanings Approved Example Example Not Approved

Acceptance (n)

ACCEPT (v)

Before you accept the unit, you must do the specified test procedure.

Before acceptance of unit, carry out the specified test procedure.

ACCESS (n)

The ability to go into or near

Get access to the accumulator for the No. 1 hydraulic system.

Accessible (adj)

ACCESS (n)

Turn the cover until you can get access to the jacks that have “+” and “–” marks.

Rotate the cover until the jacks marked + and – are accessible.

ACCIDENT (n)

An occurrence that causes injury or damage

Make sure that the pins are installed to prevent accidents.

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.

Table 2—Approved words, according to the STE Dictionary
Word Used Approved Word

Oil

Oil (TN)

Engine

Engine (TN)

Skin

Skin

Toxic

Poisonous

Absorption

Absorb (v)

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:

To pre-warm the cup with steam:

  1. Press the steam lever down.
  2. Push the lever up to stop the steam from dispensing.
  3. Pour away any excess water.

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 User Interface

The buttons shown in Table 3 appear throughout the software.

Table 3—Buttons in the user interface
Button Description

OK

Accepts the user’s changes in a dialog box and closes the dialog box.

Cancel

Closes the dialog box without saving the user’s changes.

Yes

Completes an action and closes the message box.

No

Prevents an action and closes the message box.

Close

Closes the window or dialog box.

Update

Updates a user’s changes to the data in a dialog box.

The following example adheres to the second principle of minimalism:

To edit the data and close the window:

  1. In the XXX window, type your changes to the data.
  2. Click OK to save your changes. The window closes automatically.

To edit the data without closing the window:

  1. In the XXX window, type your changes to the data.
  2. Click Update to save your changes. The window remains open, and you can proceed with other tasks.

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.

MMS Workstation Reboot

If an MMS Station is not functional, reboot the workstation, as follows:

  1. Press CTRL-ALT-DEL.
  2. Click Log Off.
  3. Click Yes to confirm you want to log off.
  4. When prompted, type your user name and password.

Note: Your user name and password are provided in the latest version of this document: SC-OM-SO-PROC.

Note: Once you’ve rebooted the workstation, the Alarm Viewer application will restart, as described in section XXX.

The following troubleshooting example follows the third principle of minimalism:

title/detection: MMS Workstation Will Not Start

detection: The workstation is plugged in and the power switch is on, but the workstation will not start.

diagnosis: An incorrect action has interfered with the normal boot process.

remedy:

  1. Press CTRL-ALT-DEL.
  2. Click Log Off.
  3. Click Yes to confirm you want to log off.
  4. When prompted, type your user name and password.
  5. Restart the Alarm Viewer application.

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.

Instructor at Awel-A-Ben

Saint-Brieu, France

Marie-Louise FlackeTrained by North-American experts, Marie-Louise continually aims to improve her skills, with a view to meeting users’ needs. Attending Webinars and conferences and accepting challenging assignments in various European businesses—including Eurocontrol, European Council, Intel, Vodafone, Deutsche Boerse, and Police Federale—helps her to be flexible in providing a sound customer experience.  Read More

Founder and Director, Business Development, at INSTRKTIV GmbH

Berlin, Germany

Ferry G.A. VermeulenAt INSTRKTIV, Ferry helps companies and brands to produce technical documentation. His company stands for content quality—both in the field of usability and in matters of liability. The manual is a legal document that not only serves as the keystone in terms of avoiding liability, but also promotes the safe and proper use of technology. Ferry has been involved in technical communication since 2006. Over the years, he has gained knowledge through training and education on European and U.S. legislation, regarding instructions, usability, user experience, Simplified Technical English, single sourcing, content management, MadCap Software and SCHEMA software, information mapping, and minimalism in documentation. Ferry earned his Masterçs of Science in Industrial Design Engineering from Delft University of Technology.  Read More

Other Articles on User Assistance Design

New on UXmatters
https://www.uxmatters.com/mt/archives/2016/08/creating-user-friendly-documentation.php?ref=doctoolhub
www.uxmatters.com
crawl=CC-MAIN-2022-05
77983
application/http; msgtype=response
sha1:UWLDAOCR436VWHTYKPHQGLMUTMVNNR5P
<urn:uuid:7c8239a0-2883-4d24-af0f-a0c84dc9139c>
2022-01-23T23:58:01Z
104.21.2.234
text/html
sha1:BWQF7JWOSGRPVREU4GUJYDDWVWMWEVGW
<urn:uuid:b7b3cc56-cc96-4127-9a70-372229fb5cd9>
https://www.uxmatters.com/mt/archives/2016/08/creating-user-friendly-documentation.php?ref=doctoolhub
response
<urn:uuid:8c4bece2-f92d-4a01-9af0-9bc8ce09fbf6>
isPartOf: CC-MAIN-2022-05
publisher: Common Crawl
description: Wide crawl of the web for January 2022
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-78
software: Apache Nutch 1.18 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.3-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/