How to Create Step-by-Step Instructions

Recommendations for Writing Documentation Text

• Online documentation text should be very concise:
  • Around 50% to 80% shorter than that of printed documents.
  • Use key words or short depictive phrases more than sentences.
•  Use step-by-step numbered list rather than paragraph to display your documentation text.
  • Write one action, step, or process per bulleted or numbered item.
  • Use “Bold” format for keywords at each step.
  • Leave sufficient white space between list items.
• Maintain consistent text styles throughout the documentation.
• Do not specify a font as this will be handled with the Cascading style sheets (CSS) for the knowledge base. (Browsers do not display all fonts, therefore the page may not appear as intended when using a less common font).
• Maintain consistent use of punctuation throughout the documentation. (For instance, be consistent with placing a period, or not, at the end of each step).
• Use generally accepted terminology.
• Consider page length, especially when using screen captures and graphics. 
  • When pages become overly long, or large in file size, split the page into smaller sections and make separate pages, using links and anchors to navigate.
  • Use animation only when it adds considerably to the understanding of the documentation.  If possible, provide a non-animated alternative for modem users.
• Use open squares or circles for bulleted lists.  This allows users to check off steps when completed.
• When providing a phone number, use the format 814-86X-XXXX.

Recommendations for Using Screen Capture in a Documentation

• Use screen captures of concepts, tasks, or steps appropriately - usually for a new concept, or for a task/step which a screen shot should explain more effectively than text.
• Use arrows to show an action or concept when the information is not explicit in a screen capture.
• Insert a Red Note Box in a screen capture to highlight really important information or warnings.
• Number each step if a screen capture conveys multiple steps.
• Add a short title to each screen capture to label what step(s) a screen capture is supporting.
• Pay attention to a balance between the graphic quality and the download speed of online documentation:
  • A maximum image dimension of 600 X 450 is recommended for a full-screen capture.
  • Use a resolution of 72 dpi (browsers maximum resolution) to minimize file size and maximize download speed.
  • Use an image editor (Adobe Photoshop, Macromedia Fireworks, etc) to compress the graphic file before posting it to online documentation.
  • If the concept or step to be conveyed involves only a portion of the screen, capture the whole screen and highlight the relevant portion.

Additional Recommendations for Usability and Accessibility

• Use Alternate Text tags with graphical images.
• Use colors that can easily be recognized, even by color-blind users.
  • Black on white background is best.
  • When possible, use less than five colors.
• Information should be ordered consistently.
• Menu options should be self-explanatory and limited in number.
• Minimize the number of hypertext links that appear in a single line of text.
  • Preferential to use vertical list of links.
• Document metatags should be used to improve searching.
• Avoid using images made up of bitmapped text.
  • Screen readers cannot read the text contained in images.
• Minimize the use of italic text as some users may find it difficult to read.
• Avoid flashing text.
• Sound and video should be used with caution and only when they aid understanding.