considerations for documentation

Use the information below to guide the composing and revising of your two-page draft for our team conference, your first completed draft, and your final draft of documentation. Be certain to save your draft with your team's name as part of the file name.


formatting

Place an "X" in the left-hand column if the appropriate formatting has been used. Please consult the "Reference Sheet for Formatting" or me if you have any questions about formatting.

x
feature potential changes
  visual distinctions between user actions and procedural results.
  accurate numbering for sequence of steps.
  portrait page layout.
  1-inch margins.
  left-justified.
  12-point font for body text.
  serif font (such as Times New Roman) for body text.
  descriptively titled headings and subheadings.
  sanserif (such as Helvetica) font for headings.
  heading font larger than that of the body text.
  bolded headings.
  appropriate use of white space to "chuck" information.
  appropriate use of borders and shading.
  appropriate use of indention to establish visual hierarchy.
  appropriate use of unordered bulleted lists.
  appropriately sized and cropped screenshots.
  well-placed callouts.
  appropriately sized illustrations.
  visual distinctions between notes or exceptions and information.
  page numbers.
  no underlining.

After working through this formatting checklist, please note any additional changes concerning formatting.


content of instructions

Use the following questions to guide your drafting and revising of documentation content.
introductions

How well does your general introduction highlight the purpose and intended audience for your instructions? How well do the specific introductions for each section explain their corresponding sections? Consider revisions, deletions, and/or additions which could make the introductions even more effective for the users.

actions and results

How well does your documentation distinguish between user actions and procedural results? In other words, are your numbered steps distinct from the images and/or descriptions of the potential outcomes of these steps? Consider revisions, deletions, and/or additions which could make your distinctions between actions and results even more clear for the users.

sequencing and sectioning of steps

How well does your documentation provide accurate and thorough sequencing of instructions? Have you documented all the steps required to begin and complete the process? Are the steps provided in the appropriate order? Is your sequencing of steps "chunked" into logical sections? Are the sections descriptively titled? Consider revisions, deletions, and/or additions which could make your step-by-step instructions more thorough and better organized for the users.

visuals

How well does your documentation depict visually the actions and results in the process? Are the screen shots and/or illustrations well correlated with the text in your steps? Are these visuals well cropped and sized? Is the text to image ratio well-balanced throughout your documentation? Are the callouts for these visuals well-placed and descriptive? Consider revisions, deletions, and/or additions which could make your visuals even more rhetorically effective for the users.

tips and notes

How well does your documentation account for exceptions, tips, and user options? Do your instructions provide additional information to help the user complete and/or better understand the process? Do your instructions account for exceptions and allow users to work through confusing points in the process? Consider revisions, deletions, and/or additions which could make your documentation even more contextualized and user-friendly.




Other Documentation Project Links:
Overview of Documentation Project | Formatting Reference | Downloadable Process Notes Form | User-testing Worksheet | Screen Shot Instructions

421 syllabus | 421 calendar