Writing Procedures
Which is easier to read, this.....?
or this?
Procedures
Where are procedures used?
Write installation instructions as procedures
Write troubleshooting topics as procedures
Write tutorials as procedures
Procedures include four parts
Typical procedure
Introductions
Help users choose which procedure they need
Explain difference between procedures
Explain prerequisite procedures
Explain unfamiliar concepts
Organize step-by-step instructions
Write steps in the order users must perform them
Write steps in order users must perform them
Include relevant information in the step
Write one step for one action
Number the steps
Limit number of steps
Divide one long procedure into two
Write a separate procedure for duplicate steps
Combine trivial steps
Grammar for steps
Start procedure with a lead-in sentence; let the steps finish the sentence
Tell users where to start and end the procedure
Start steps with a verb (command)
Use same verbs for same actions
Write steps in present tense
Write parallel and active sentences
Write an “If” clause for alternative steps
Follow user interface style
When do I use numbered steps?
Write procedures in numbered steps when
Write procedures in paragraphs when
Write procedures in paragraphs when (continued)
Procedures have too few steps
Explanations
Give users information they need to move on to the next step
Describe what user should see after they complete step
Describe options
Include code
Alternate way of completing a step
Describe how a feature works if not obvious
Describe unfamiliar concepts
Describe problems user may have when following steps
Tell users what to do after completing steps
Tell users what happens next
Write explanations
If explanation has too many steps, cross-reference a separate procedure
Cross-references to related procedures
Cross-references to related concepts
Writing Exercise
Installation guide
Installation instructions
Write automatic installation procedures
Email: kgallag@rpbourret.com
Home Page: http://www.rpbourret.com/kgallag/index.htm