Descriptions, processes, and instructions

295 views
258 views

Published on

How to write clear, concise documentation in the workplace

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
295
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
0
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Descriptions, processes, and instructions

  1. 1. Descriptions, Processes, & InstructionsKaren O’HaraNovember, 2012
  2. 2. DOCUMENTATIONExamples include operations manuals, productdemand specs, consultant study reports, salesliterature1. Descriptions: lists the features, capabilities & processes that a mechanism may use  May begin with a sentence definition: A domestic dog is a four-legged mammal that may function as a pet, a worker, or a show competitor.
  3. 3. DOCUMENTATION (CONTINUED)2. Process Analyses: how something works  Example: how an air bag works3. Instructions: how to do something  Example: how to send a fax
  4. 4. TIPS FOR WRITING DOCUMENTATION Start with an introduction (tell us what we are about to do) Provide list of materials needed Keep it simple; no jargon (think of the “For Dummies” books) Write short, imperative commands, using active voice  Avoid “Now you want to…” or “File>New>New Project”
  5. 5. VISUAL CUES IN DOCUMENTATION Add diagrams, photos, captions to help inexperienced users Number steps and stick to one action per step. Numbers indicate sequence, order, counting Bullet points indicate notes, in no particular order Highlight safety warnings Provide clear, intuitive headings to subdivide numbered steps
  6. 6. EXAMPLES OF GRAPHICS IN DOCUMENTATIONIKEA examples AVSIKT roll front cabinet 18x17" ALSVIK dual central kitchen faucet
  7. 7. LESSONS FROM USER TESTING Images may be more valuable than text in some situations • Clear, intuitive images can replace words • Color makes a difference to many users • Images need to be consistent in size, placement, etc. Experienced users can overlook poor instructions; inexperienced users will become confused, frustrated or will feel “dumb” • Important to set expectations: we’re testing my instructions, not your abilities, etc. • Asking users to “think aloud” can identify problems • Alertness to visual or auditory cues (frowning, sighing) is important
  8. 8. HELPFUL RESOURCES Howcast: video tutorials on all sorts of subjects The Product Manual Archive: Classic owners manuals, catalogs, hang tags, and other things Instructables: eBooks, videos, and illustrated tutorials on many subjects Warning Sign Generator: a place to experiment with design and content of warning messages
  9. 9. THE ENDFollow me on TwitterVisit my WorkplaceWriting Blog

×