Introducing procedures
A discussion list summary article, by Abby Kasper
As writers, we are constantly challenged to rethink our writing styles and improve the way we present information to global audiences. Recently, the following question stimulated an animated discussion in the discussion list community.
We are considering changing the style we use to introduce a procedure. Does anyone have thoughts about the pros and cons of either of the following styles:
[conceptual overview of a task; for example, adding new employees to a database]
To add a new employee:
1.
2.
OR
[conceptual overview]
Use the following procedure to add a new employee:
1.
2.
Most writers who responded to this query expressed a willingness to use both styles but preferred to introduce a procedure with an infinitive phrase. They then described how they use this style to address two important issues: creating documentation that is easy to translate and documenting procedures concisely.
Writing for Translation
Infinitive phrases have a valuable place in technical writing, but they must be used carefully. The infinitive phrase used by an English-speaking writer may be reduced to a single word when it is translated to another language. As a result, separating the word “to” from the verb associated with it can cause structural problems, so it is important to keep the components of an infinitive phrase together. For example, the following list would translate poorly:
Use this device to:
* measure room temperature
* detect intruders
* generate an audible alarm
Writing Concisely
Using a short but descriptive infinitive phrase to introduce a procedure can reduce the word count of a document and provide visual cues that help the user locate the information required.
Introducing a procedure with an infinitive phrase can reduce the word count of a document by eliminating frequently used phrases such as “Use the following procedure.” Contextual clues (such as numbers) indicate that the user must perform an action, so the clarity of the instructions is not harmed.
To further enhance the clarity of a document, some writers create a heading for product overview information and also format the infinitive phrase as a heading. These visual cues quickly lead users to the information that is most useful to them. A user who needs basic conceptual information about a function of a product can read the overview information before beginning the procedure, and an experienced user trying to remember the first step of a procedure can easily skip the overview information and locate the procedural information.
Conclusion
In conclusion, most technical communicators who responded to this style question prefer to introduce procedures with carefully constructed infinitive phrases, but were willing to use descriptive, complete sentences if the audience needs justified that choice.
Lornkanaga said,
April 23, 2007 at 9:26 am
I’ve found that using the least number of words possible usually alleviates confusion.
When writing instructions, complete sentences should be thrown out the window. Even “To add a new employee:” is too long–”Add new employee:” or even “Add employee:” is more to-the-point.
The more explanation given, the more confused a learning user can get. Most people just want to be told, “Do this:” so they can get on with their lives. Any explanation, if needed, should be placed *after* the instruction so that the user has the option of reading it or skipping to the next step.
Douglas Sunlin said,
May 30, 2007 at 12:12 pm
For my manufacturing procedures, I use a simple declarative summarizing the action, followed by the discrete steps. This provides the reader the option of skimming the topics as a refresher, or delving into the text for details.
An example:
Calibrate the Crystal Shifter
1. Measure the crystal shifter’s current setting.
2. Adjust the crystal shifter’s setting to match spec.
3. Measure the crystal shifter’s setting to ensure that it has been properly set.
-Douglas Sunlin
Carol Hedberg said,
May 31, 2007 at 10:41 am
I never precede a numbered procedure by a sentence phrase and colon! Procedure steps should stand alone as imperative statements, as in Douglas Sunlin’s example. My favorite way to introduce a procedure is a heading in the form of a participle phrase such as, “Introducing Procedures,” or “Calibrating the Crystal Shifter.” Of course, the context determines what is helpful to the reader. This heading approach is best in a document designed to provide procedures. I find that when introducing procedures becomes awkward for the writer, the audience and purpose of the document are poorly defined; that is, the writer is trying to do too many things at the same time. Passively written headings with complex hierarchies are immediate clues that this is happening. The reader will not be able to navigate such a document to find a procedure, regardless of howw it is introduced.
malachai said,
July 31, 2007 at 2:10 pm
“As a result, separating the word “to” from the verb associated with it can cause structural problems, so it is important to keep the components of an infinitive phrase together. For example, the following list would translate poorly”
Translations are not literal. I don’t see why this list would translate poorly. Why would keeping the “to” and the verb together translate better? Would the translator just not translate it idiomatically into the target language in both cases?