Comments on: Introducing procedures http://www.stc-techedit.org/2007/04/20/introducing-procedures/ Sun, 06 Jul 2008 20:58:35 +0000 http://wordpress.org/?v=2.2 By: malachai http://www.stc-techedit.org/2007/04/20/introducing-procedures/#comment-282 malachai Tue, 31 Jul 2007 18:10:34 +0000 http://www.stc-techedit.org/2007/04/20/introducing-procedures/#comment-282 "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? “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?

]]> By: Carol Hedberg http://www.stc-techedit.org/2007/04/20/introducing-procedures/#comment-232 Carol Hedberg Thu, 31 May 2007 14:41:10 +0000 http://www.stc-techedit.org/2007/04/20/introducing-procedures/#comment-232 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. 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.

]]> By: Douglas Sunlin http://www.stc-techedit.org/2007/04/20/introducing-procedures/#comment-227 Douglas Sunlin Wed, 30 May 2007 16:12:25 +0000 http://www.stc-techedit.org/2007/04/20/introducing-procedures/#comment-227 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 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

]]> By: Lornkanaga http://www.stc-techedit.org/2007/04/20/introducing-procedures/#comment-166 Lornkanaga Mon, 23 Apr 2007 13:26:59 +0000 http://www.stc-techedit.org/2007/04/20/introducing-procedures/#comment-166 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. 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.

]]>