TCT Chapter 20: Instructions and Documentation

• The types of documentation
• Instructions—Describe how to perform a specific task
• Specifications—Describe in exact detail how a product is assemble or how a process is completed
• Procedures/Protocols—Ensure consistency and quality in the workplace

• Basic features of documentation
• specific and precise title
• introduction with background information
• list of materials, parts, tools, and conditions required
• sequentially ordered steps
• graphics
• safety information
• measurement, test, and quality control procedures (for specifications)
• conclusion that signals competition of the task (describing finished product and offering troubleshooting advice)

• Cross-cultural awareness
• Verbal considerations
• Translate the text
• Use basic English
• Check meanings of names and slogans
• Design considerations 
• Use icons carefully
• Use images carefully

• Organizing documentation
• Introduction
• State the purpose
• State the importance of the task
• Describe the necessary technical ability
• Identify the time required for completion
• Motivate the reader
• List of parts, tools, and conditions required
• Lists the parts required
• Identify tools required
• Specify special conditions
• Sequentially ordered steps
  • Use command voice
  • State one action per step
  • Keep steps concise
  • Number the steps
  • Add comments notes and examples
  • Provide feedback
  • Refer to the graphics

• Safety information
• Danger
• Warning
• Caution

Instructor Commentary: Instructions

• Instructions often have one or more of these problems:
• Instructions do not account for audience
• Instructions should be user-centered rather than systems-centered
• Instructions do not match real-world experience
• Instructions are unappealing and obfuscating

Sample Question:
Which is not one of the three problems when creating instruction inserts?

1. instructions are not complex enough
2. instructions do not account for the audience
3. instructions are unappealing

TCT Chapter 10: Designing Documents and Interfaces

• Five principles of design:
• Balance: the "weight" of a page is evenly distributed, but not necessarily symmetrical. Discussed through basic weighting guidelines
• Alignment: established information weight through horizontal and vertical positioning
• Grouping: keeping like things together
• Consistency: building meaning through repetition
• Contrast: kinda the opposite of consistency—making elements look distinct to get attention

Sample Questions:
Which one is NOT a principle of document design?

1. Balance
2. Grouping
3. Consistency
4. Contrast
5. Size

What is the most prominent feature of design in technical documents?

1. Balance
2. Alignment
3. Grouping
4. Consistency

Instructor Commentary: Design

• Qualities of good design:
• Good design is invisible
• Good design is persuasive
• Good design guides the eye
• Good design uses whitespace effectively
• Good design requires careful attention
• Graphics should be consistent in size, shape, style, and orientation unless there is a specific reason to deviate.

Sample Questions:
What is not a quality of good design?

1. Invisible
2. Persuasive
3. Guides the eye
4. Does not use white space

True or false: people notice good design

TCT Chapter 12: Revising and Editing for Usability

• Four levels of editing:
• Revision
• Substantive editing
• Copyediting
• Proofreading
• Usability Tests(informal to formal):
• Document markup
• Read and Locate test
• Summary test
• Protocols
• Journal or tape recording
• Surveying
• Interviewing
• Focus groups
• Laboratory testing
• The four questions usability testing is designed to answer:
• Can they find it?
• Can they understand it?
• Can they do it?
• Is it safe?

Sample Questions:
What are the four levels of editing?

Which level of editing best defines the following description?
"Pays special attention to the content, organization, and design of the document."

1. Revision
2. Substantive editing
3. Copyediting
4. Proofreading

Instructor Commentary: Usability

The basic concept of usability is that documents and products should be usable in the real world environments where they function.