Hello and welcome to No. 2 edition quick tips, articles on technical documentation best practices. This issue covers writing procedures and is a refresher on the best practices in procedure documentation.

Thank-you and have a great day,

Stefano

Writing procedures

One of the most important parts of the Users and Members CHM files are the procedures and processes that users must follow to install, configure and use the various parts of SMS.

Parts of a written procedure

Written procedures should ideally follow technical writing guidelines and best practices¹.

 Procedures should have:

1. Procedure title
   
   Procedure titles should be coded as headings (e.g. H2,H3,H4) and be bold and should start with the gerund form of the verb.
   (verbs ending in “…ing” e.g.: creating, inserting, importing, printing, scanning, etc…)
   
   Avoid:
   How to print labels
   How to activate in-store batches
   How to run reports
   
   Preferable:
   Printing labels
   Activating in-store batches
   Running reports
   
   The reasons, it shortens procedure titles and may also help readers more easily find information, instead of having to look through a long list of items all starting with “How to…”
   
   Studies have shown that when users read the gerund-form (…ing) of a verb, they instinctively know it will be a procedure that explains “how to do” something.
2. A brief description/objective explaining what the procedure accomplishes and any pre-requisites needed.
   
   The brief description/objective explains what the procedure does or what the user must have done to prepare (if required) prior to performing the procedure.
3. Procedure introduction (can be combined with the description above)
   
   A procedure introduction can be added to the end of the description above or if it is placed separately, should be bold. It basically explains in a very short sentence what the user is about to do and reinforces the instructions. Strangely enough, it is often written in a more passive tone in the form:
   "To accomplish such and such, follow the steps below:"
4. Finally, the actual written steps.
   

   Procedure steps should be written in short, direct, sentences written in an active voice and in the infinitive form. If a step is a complete sentence end with a period.

   Note: Avoid ending sentences with semicolons (;), I realize why this is done, as statements in Delphi end with semicolons and therefore it is natural for application specialists/developers to follow the same logic in documentation. Ideally sentences should end with a period if they are full sentences and have nothing at the end if the step is just a few words.

Active voice/infinitive form

Avoid:

     The Go button should be clicked. (passive voice/past tense)

Preferred:

     Click the Go button. (direct active voice/infinitive form)
     or
     Click Go

Action/consequence order

Always explain what an action/step will do before the action itself, this avoids users doing an action before knowing the consequences of that action:
(users have a tendency of sometimes blindly following instructions before reading the entire sentence.)

Avoid:

Type Format and press Enter to delete all the files in your computer.

Preferred:

To delete all files in your computer type Format and press Enter.

Example procedure

The example shown below is a prototypical procedure, although these are best practice guidelines, the parts and layout may not always be suitable for all procedures you may encounter, but in most cases, when possible, procedural writers should use best practices.

Creating an operator – SMS application To create a new operator, log in with a user that has an equivalent or a higher security profile than the operator to be created. In other words, an "assistant manager" cannot create a "manager", "owner" or a "programmer". This is necessary to prevent a lower profile user from assigning themselves or tampering with a higher security profile. To create a new operator follow the procedure below: Under the Manage tab, expand the Program sub-menu if necessary, and click Operators. Enter a non-existent Seq. number in the Manual code and press Enter. SMS prompts that the user does not exist and asks to create it, click OK. Enter the new Operator number, this can be different than the Seq. number. Enter the other new operator information according to the required information guidelines. Repeat steps 2 to 5 for all operators to be created. Once all operators have been created, the new operator information must be deployed to the front-end workstations on your network using the deploy changes task.

A. Procedure title B. Procedure description Note how the description provides some requirements before the procedure is started. C. Procedure introduction D. Procedure steps

¹Guidelines referenced from whitepaper: Writing Procedures by Lee Bachelor, Technical writing instructor at Humber College, Ontario.