Questions to answer before you start

• Who can show you this procedure end to end?
  (Can you capture it using Lync meeting recordings or Jing?)
• Who’s going to be using this documentation to follow this procedure?
  • Beginners, less experienced staff, or people providing initial training to a group: Screen shots in sequence
  • Advanced people or  more experienced staff: Text-based, brief (1 or 2 page) “quick start”
  • Both: Offer both formats. Sometimes the quick start can also guide the table of contents for the advanced version.
• How often will the same person follow this procedure?
  • Once or twice: Details are good
  • Repeatedly: A quick start or summary version is important
• Do you have all the information you need to structure the decision tree for this procedure?
• How many times does the decision tree diverge, with different actions for “yes” decisions than for “no” decisions?
  • Not very often:
    One consolidated document can be OK
  • Frequently:
    A linked (online) document including several short pages may help guide people through steps, with people choosing the path they need through the procedure.

Page templates

Quick Start

• One sentence summary of what the procedure is, who does it, and what it should accomplish
  (example: “Foundation staff use this procedure to update the database of information about alumni accomplishments over the past year.”)
• What starts this procedure
  • A checklist of all the items needed to successfully complete the procedure
  • Where each item goes during the procedure

(Sort your checklist by the order in which it will be encountered during the procedure.)

• Numbered outline of the best case scenario
  • (Optional) “If (alternative case), see step 7” branches off to the alternative version
  • This sequence should be the fastest path from start to  success.
  • Success state? Done!
    Failure state? See troubleshooting at (location X).
• (Optional) Numbered outline of the alternative cases encountered above.
  • This can describe some other common paths from start to success.
  • The goal here is to describe when everything goes correctly through a less common path.
  • Examples: The fastest path could be “log in to IllinoisNet Wireless.” The alternative path could be “visiting another campus? Log in to eduroam instead. After that, connect to this remote desktop server, then continue with step Y.”
• Tips for writing brief quick starts:
  •  Try hand-writing or drawing the key points on an 8.5×11 sheet of paper before you start typing. You’ll have both a visual reference and a starting outline.
  • Failure states may need troubleshooting that’s too long and complex for a “quick start.” Use other documents for complex troubleshooting.
  • Keep the numbered outline the same between the quick start version and the detailed version, so that the detailed version can be used for reference.

Detailed version

• One sentence summary of what the procedure is, who does it, and what it should accomplish (“Foundation staff use this procedure to update the database of information about alumni accomplishments over the past year.”)
• Getting Started
  • A checklist of all the information needed to successfully complete the procedure
    (ideally, the same one as the Quick Start used)
  • Where to get missing information from
  • Where to start the procedure (URL? Paper form? Elsewhere?)
•  Step by step guide through the procedure / interface
  • Draw focus to the areas of the procedure / interface that need action.
  • For online interfaces, “one screen at a time” is a good “chunk size”. Show the full screen and make a bulleted list of what each selection field needs to have entered in it. 
  • The last item in a “chunk” is usually the change-screen action (often “Next” or “OK” or “Save”, sometimes “Cancel”)
• When the decision tree diverges, follow the best-case scenario path first.
  • If everything works smoothly, this will be the shortest path from start to success.
  • If the “suboptimal case” scenarios are either detailed or repetitive, consider storing them in a different location and linking to them rather than repeating them over and over (especially if the document is meant for printing).
• Outcome:
  • What’s the success state?
  • What is/are the failure state(s)?
• Troubleshooting the failure state(s)
  (If this is more complicated than “contact X for more help”, the troubleshooting steps may be a different document.)

Troubleshooting

Guidelines:

• Most common problems first
• Less common problems later

Possible formats:

• Question & answer (FAQ style)
• Diagnostics
  • Issue
  • Symptoms
  • Diagnosis
  • Resolution
• Sequence of diagnostics
  • Put the diagnostic sequences in the order in which they should be tried