Technical Documents: Types and Standards Week 6 Technical Communication Fall 2003, DAHMEN

General Types of Tech Docs Specifications Brief Instructions Procedures Long Instructions Documentation Manuals

Specifications Used to create standards Proves compliance Assures safety and quality in  Manufacturing  Building  Installation  Materials  Size, shape or weight

Typical Audiences for Specs Customers Contractors Suppliers Programmers Inspectors

Types of Specs Industry standards Government standards Functional specs Internet specs

Typical Parts of Specs Introduction Description Component parts and their descriptions References to other specs

Usability Considerations for Specs Use (needs analysis) Terminology Navigation and organization Standard format Style sheets/templates to ensure consistency Active voice for instructions

Brief Instructions and Their Format Part of layered documentation Reminders for current users Short procedures Common formats  Wordless instructions  Assembly instructions (one page)  Quick-reference cards (one time or reusable)

Typical Audiences for Brief Instructions Consumers Users doing specific tasks

Typical Components of Brief Instructions Title Overview of task Step-by-step instructions Diagrams Follow-up info (where to go next) Contact info for company

Issues for Usability Use (task analysis) Assess appropriate length Terminology/ consistency Test instructions Style sheets/templates to ensure consistency Active voice for instructions Maintain simplicity

Procedures & Their Use Provide information, steps and guidelines Longer than brief instructions, not as long as manuals Often situation specific  Emergency procedures  Set up procedures  Processing procedures  Training procedures  Usage procedures

Typical Components for Procedures Title Overview List of steps Warnings/cautions Procedure number Revision date

Usability Issues for Procedures Use (task analysis), especially location Audience analysis Technical expectations Test document Active voice for instructions Chronological order

Documentation and Manuals ‘Layered’ information for different information Information for a suite of products More and more online in format Designed for  End users  Managers  Sales reps

Typical Components Overview “Access points” Chapters References TOC/Index

Usability Issues for Manuals Assessing the medium/format Choosing appropriate information Usage of info by user Appropriate visuals Appropriate writing style for audience

Technical Marketing Combining Promotion/Advertising with Tech Com Persuade others to purchase product or services Emphasis on technical specs to promote product

Typical Formats of Tech Marketing Brochures Web pages Letters Promotional Documents

Typical Components of Marketing Name of product/service Type of product/service Features of product/service Visuals FAQs

Usability Issues for Marketing Know audience Use appropriate (persuasive) language Effective graphics/layout Often single page Be aware of promotional aspects

Short Assignment Find an example of bad documentation of any type discussed in this chapter. Then, brainstorm what makes this documentation bad. Last, draft a formal memo to the writer/company outlining the things he/she should do to improve the next version of the document. Due: Next Wed/Thursday Length: 1-2 pages