June 2018
Text by Robert Meyer

Image: © wosephjeber/istockphoto.com

Robert Meyer is a technical writer and content developer currently working in Germany. During a long and varied technical writing career in the US and Europe, he has authored documentation across a range of domains: aerospace, biotech, IT, and remote process control. He enjoys helping new technical writers get started in the business.   


meyer.robert21[at]gmail.com


 


One word, one meaning

Think using a controlled language is too complicated, not suited for your market or simply too “controlling”? Think again. The S100D and the ASD STE-100 are two free standards for Simplified Technical English that could help you produce more user-friendly documents with no new software needed.

Has your company recently sold equipment to a vendor who requires MIL-SPEC (military specification) documentation? Or perhaps, despite the fact that you are not a native speaker, you find that a lot of your writing is in English and word choice really gives you a headache. Or perhaps your product manager has asked for some improved product installation documents after a grueling product installation/validation cycle.

If you have been in the field of technical communication for a while you have no doubt heard of Simplified Technical English, controlled language, and the foreboding acronyms S1000D and ASD STE-100. Your fellow writers might have even given you their honest opinions: too complex, too expensive, not user-friendly, only for the aviation industry, etc. You might even have been put off by the idea of someone “controlling” your language. After all, language is a living thing. Whatever your experience, perhaps one or both of these standards are worth a look. They are both available online at no cost and are recognized worldwide. This article will give you the basics, and you can sample the science via a free download to see if you want to add them to your writing/editing toolbox.

What S1000D and ASD STE-100 are… and aren’t

Both standards are implementations of the theory of "controlled language" or "rule-based writing", ideas that have been studied, debated, developed, and implemented in different forms since the 1930s. To quote from an excellent article by Herbert Kaiser from tcworld 3/16:

"A language is guided by a few rules. The principles of language are based on the insights gained from research into comprehension. Information that is structured according to specific rules and recipient-oriented is understood better by the user."

In more basic terms, these standards can be thought of as highly specific formatting and style guides for technical English.

S1000D started as a research project by engineers at The Boeing Company, who wanted to standardize English-language maintenance manuals on Boeing aircraft deployed worldwide. The standard has evolved considerably and is now known as an XML specification for preparing and managing equipment maintenance and operations information. As such, it is more geared toward the format and content of technical documentation sets than the writing of it. It was initially developed into a standard by the AeroSpace and Defence Industries Association of Europe (ASD) for use with military aircraft, and it has a steering committee that maintains control of the specification.

The current ASD STE-100 was developed from early work in the 1980s and is a controlled-language specification originally developed for writing text in aerospace industry maintenance manuals. It is a strictly limited and standardized subset of standard English and is officially trademarked as Simplified Technical English (STE). It is not an XML specification and is probably more like a "style guide on steroids".

Neither one is a software application or a machine-translation tool. Though both had origins in the aerospace maintenance industry, their particular use is NOT restricted to this industry. In fact, the stakeholders in the ASD STE-100 consortium have enthusiastically pushed for the standard’s use in many other industries. Both standards, true to their aircraft-maintenance pedigree, are particularly well-suited to writing procedures – even computer program procedures – but not exactly made for frothy web-content writing.

S1000D

You will probably find the S1000D more useful as a “big picture” of the content and layout for technical material, whether you plan to build XML data schemas or not. Say you get tasked with writing a manual for a new piece of machinery. If you don’t already have a good template, you can probably base at least your table of contents on the list of data module types defined in the S1000D specification.

First, download the standard from the S1000D website.

Naturally, it is in XML and the latest PDF (Issue 4.2) is more than 3500 pages, so be sure to leave it as a PDF. In the specification, the contents of each required data module (service bulletin, description, wiring data, maintenance schedule, etc.) are rigorously defined, which makes this an excellent reference check list for that new manual you were asked to develop. If your manual contains all the components listed in this specification, it will probably be good enough as a first draft, with later additions or revisions based on the specific product and customer requirements.

Image 1: Pages from S1000D Issue 4.2 showing prototype pages of a maintenance manual.

 

Though it is not meant as a how-to manual, the S1000D specification walks you through each section an S1000D-approved manual must have, using a maintenance procedure for a bicycle instead of a Boeing. At a minimum, any MIL-SPEC documentation would have to have the XML schemas specified to be valid.  There are thousands of other more detailed schemas/descriptions for every conceivable piece of equipment bought by the military (see everyspec.com).  You will find the description very effective, though not exactly pretty, with the XML markup for each component in the schema shown. It doesn’t get simpler than this. You follow the template, make it customer-specific, and check the legal requirements for safety notes and warning messages. Interestingly, all the text written in the specification meets ASD STE-100 standards.

ASD STE-100

ASD STE-100 is a writing and editing tool. After your manual is designed and formatted, you will drill down to the writing to make the procedures as foolproof as possible. To do so, and to help your customers with a limited understanding of English and the need to get a procedure done absolutely correctly, you might be well advised to check some of your text against the ASD STE-100 (Simplified Technical English or STE) specification.

Though STE was developed to avoid translation costs, many machine translation systems use its rule-based methodology to make translation quicker and cheaper. Again, for a thorough background on ASD STE-100, see Herbert Kaiser’s article. To put it simply, STE is built on the assumption that most, if not all, maintenance procedures can be explained and understood using a controlled dictionary of 900 English words clearly defined for one single use and 65 strict rules on grammar and the usage of these words in context. To quote Herbert Kaiser, STE…"can be understood so clearly from its structure and word selection that users with minimal knowledge of English understand this technical information immediately and can implement it exactly."

Just like the S1000D, development of ASD STE-100 started in the late 70s, originally as a standard for the European aerospace and defense industries. Since then, it has evolved into a standard widely used by international corporations, especially for maintenance and installation text. Now only three percent of the dictionary terms are limited to aerospace usage. Download the specification (Issue 7) here. The 382-page PDF is free of charge and new versions are listed periodically.

Put on your specs!

The first 89 pages of the STE specification contain the grammar rules. Experienced technical writers will not find anything really new in these rules; they are standard technical writing rules (both in English and German). However, they are well illustrated with vivid examples. The rules in Section 9 (Writing practices) are worth reviewing, as the examples show how to change sentence structure to accommodate the approved words in the STE dictionary.

The dictionary follows in Part 2. This dictionary doesn’t give definitions; rather, it lists the words accepted for use in the standard and gives you an approved and not-approved use of the word, if applicable. Note that many of the not-approved uses involve the passive voice. This rule is included in Section 1.

 

Image 2: Entries in the ASD Simplified Technical English (STE) specification dictionary

 

Here is an abbreviated version of Herbert Kaiser’s explanation of the STE methodology used:

  1. Keyword (part of speech): This is the keyword entry with information on the type of word, because every permitted word in STE is permitted only as a specific word type. For example, “test“ is only permitted as a noun (the test), but not as a verb (to test).
  2. Approved meaning/ALTERNATIVES: This contains the definition of a permitted word. Alternative phrasings are given for words that are not permitted in STE. These are listed in lowercase letters.
  3. APPROVED EXAMPLE: The entire text in this column is in capital letters. This indicates that everything conforms to STE. These are sample sentences from technical manuals for the keywords displayed in column 1. If the keyword shown in column 1 is not permitted in STE (lowercase letters), this column has sample sentences with the alternatives provided in column 2 (capital letters).
  4.  Not approved: This also deals with sample sentences from technical manuals. But the lowercase letters indicate that the sentences do not conform to STE. The column is only filled for keywords that are not permitted. Column 4 is empty if the keyword conforms to ASD STE-100.

Though it may seem overly strict, the STE attempts to limit a word to as few uses as possible in a text. Those who read (and write) modern English as a second language should welcome that. To cite an example from Wikipedia: The word "close" can only be used in one of two meanings:

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

The verb can express closing a door or closing a circuit, but cannot be used in other senses (for example to close the meeting or to close a business). The adjective "close" appears in the dictionary as an unapproved word with the suggested approved alternative "near". So STE does not allow "do not go close to the landing gear", but it does allow "do not go near the landing gear."

In addition to basic STE vocabulary listed in the dictionary, Section 1 (Words) gives explicit guidelines for adding technical names and technical verbs that writers need to describe technical information. For example, words or phrases such as overhead panel, grease, propeller, to ream, and to drill are not listed in the dictionary, but qualify as approved terms under the guidelines in Part 1, Section 1 (specifically, Writing Rules 1.5 and 1.10). Of course, it might be interesting or professionally beneficial to read through all of the dictionary entries, but you can also search some of your most-used words to see how they are adjudicated. You might be surprised! Phrases or words you have been using for years may appear as "not approved", while other words you thought were too abstract are included as "APPROVED EXAMPLE".

Don’t expect the STE specification to solve some of your more thorny writing questions. For example, I (and a product manager) once spent a lot of time debating the word "fitting", as in "injection nozzle fitting" and got nowhere. Somehow, the phrase translated directly as "screwed fittings" from the base language, which didn’t really work in English, of course! Not even the STE dictionary could help me with this. In any case, treat STE as another resource, and keep in mind that the specification was originally aimed at an audience that did maintenance and repair of aircraft engines, so some of the approved examples seem a bit clunky (I would NEVER write that!). Also, the dictionary does not deal with spelling issues (American or British spelling). The list of international companies that have incorporated the STE into their in-house writing/editing systems spans the alphabet, from Avaya to Xerox.

There’s an app for that!

If you like what you see in the spec, but your company hasn’t implemented it, you can download several plugins that will search through your document for words listed in the dictionary and offer the alternatives in the specification. Techscribe offers an ASD STE-100 plugin "Term Checker" available for download with review and purchase options.

Etteplan also has a tool that is a little more muscular, but includes the ASD STE-100 in its search routine, as well as standard acronyms and other specifications. Of course, just dropping an approved STE word into a sentence will not always work, so it goes without saying that you will have to re-edit and proofread after any STE validation work. And don’t despair, STE is considered a living language and accepts feedback from users to improve it or argue with the specification. You can download a feedback form on the ASD STE-100 web page.

With an understanding of the intended uses for these two specifications (S1000D and ASD STE-100) and a bit of wordsmithing, you can improve the clarity of any maintenance and installation documentation you write in English. And the next time you see "ASD STE-100 compliance?" on the project kickoff "wish list", you can confidently say: "Already implemented! Next?"