Yvonne Chypchar Task-Based Technical Documentation
Content in a box write it down.
Audience What information comes first? Visual Structure
NASA Space Shuttle Columbia, January 2003
Foam debris hits wing on take-off. “The debris struck the leading edge of the left wing, damaging the Shuttle's thermal protection system (TPS), which protects it from heat generated with the atmosphere during re-entry.” http://en.wikipedia.org/wiki/Space_Shuttle_Columbia_disaster
16 days later, Space Shuttle Columbia explodes upon re-entry February 1, 2003
Studying the problem
Edward Tufte “ PowerPoint does Rocket Science” http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0001yB&topic_id=1
The skill of writing is to create a context in which other people can think. Edwin Schlossberg
Does this document create a context in which you can think?
“…the cognitive style of PowerPoint reinforced the hierarchical filtering and biases of the NASA bureaucracy during the crucial period when the Columbia was damaged but still functioning.”
TASK BASED DOCUMENTATION
1.Who is your audience?
• Skill set • Education • First language – Is it English, French, Portuguese? • Age • Social-Economic status
2. What information comes first?
• Concepts • Procedures • Processes • Examples • Definitions • References • Diagrams
3.What is the visual structure of the document?
Easy to scan Headings Diagrams Information in logical blocks
Procedure – a set of steps, which a user performs. Starts with a stated goal or purpose for the set of steps. Contains: • Actions/steps Sometimes contains: • Decisions (and/or) • Repeated actions
HEADINGS
Reader Question Clues to generate heading The Purpose (function) of x is to … What is the purpose of function of x? • Procedure • Process • Structure What kind of information is this? • Concept • Principle • Fact • Classification • Definition • Example How should I use this information? • Introduction • Background • Importance • Rationale Why did the author write this? • Purpose • Objective
“ing” words • Creating a File • Deleting a File Infinitives • To create a file: • To delete a file:
The checklist – A useful tool for task based documentation
What comes first
“…readers recall information they perceive to be more important more frequently than information they perceive to be less important. Carol S. Isakson & Jan H. Pryridakis Influence of Semantics and Syntax on What Readers Remember
The structure of the sentence influences what we perceive as important.
Microsoft will release its new platform next week. This is an independent clause . • It can stand on its own. • It’s complete.
Subject and predicate Microsoft will release its new platform next week .
If the code passes Quality Assurance , Microsoft will release its new platform next week. This is a dependent clause . • It is incomplete. • It relates to the independent clause. • It cannot stand on its own.
Readers perceive that information in independent clauses is more important. They have a tendency to remember that information more. If the code passes Quality Assurance , Microsoft will release its new platform next week .
Put the important information in the independent clause . You decide what is important based on your audience, your knowledge/expertise, or other reasons.
Customers will be able to download the software next week for running the VE150 algorithm. Customers will be able to run the VE150 algorithm by downloading the software next week.
Customers will be able to download the software next week for running the VE150 algorithm. Customers will be able to run the VE150 algorithm by downloading the software next week.
Audience expectations and needs Audience What Structure comes first? Layout can impede NASA PowerPoint understanding or misrepresented the facilitate it. severity of the NASA PowerPoint problem. Important presentation – point hidden in tiny impossible to read. bullet.
Good Books
Action painting by American artist Jackson Pollack. Specific audience.
ychypchar@gmail.com www.aimetis.com
Recommend
More recommend