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/ThursdayLength: 1-2 pages