writing memos
DESCRIPTION
TRANSCRIPT
BIOINF 2202: Dental Informatics Seminar
Instructors: Titus Schleyer, Heiko Spallek
Writing technical documentation in IT
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 2 of 18
A fundamental problem
“Nobody reads manuals.”Heiko Spallek,
always
Whose fault is that? The users’ or the writers’?
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 3 of 18
Why don’t people read manuals?
• “No time.”
• “Can’t find what you are looking for.”
• “Can’t understand a thing.”
• “The instructions don’t work.”
• “What I want to do isn’t in the manual.”
What is really behind these statements?
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 4 of 18
Documentation is a package
• Content
• Format
• Layout
• Language, grammar, style
• Usability
Parts Whose job is it?designer, developer, programmer
communications specialist, technical writer, manager
}technical writer, editor
everyone’s!
Writing good documentation is a team effort!
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 5 of 18
Documentation as part of the software life cycle
Programming
Specifications Testing
Maintenance
Documentation
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 6 of 18
Types of documentation
• Tutorial
• General, thematic
• Reference
• How to/FAQ
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 7 of 18
A few questions to ask before writing …
• Who will use the document?
• How will they use it?
• Does the documentation contain the information to help the achieve their goals?
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 8 of 18
Audience characteristics
• IT skill level• contextual knowledge (e.g. about similar
programs)• type
– programmer/developer– end user
• frequent• occasional• rare
• many times: multiple audiences!
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 9 of 18
Some quality aspects of good documentation
• concise
• complete
• up-to-date
• free of jargon
• well organized
• accurate
• consistent
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 10 of 18
In-class exercise: Complete a task with the provided documentation
• Excel 2003: Record/accept/reject revisions made by others in a spreadsheet.
• UPMC CTMA: Register a patient into a new study.• Turbo Prolog Reference Guide: Find out how to close a
window.• CorelDraw: Create this type of shape: • Access: Connect an Access database to a table in a
Foxpro database.• RoboHelp: Find out what “books” and “pages” are in
RoboHelp parlance.
• Please record the steps you used to complete the task!
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 11 of 18
Parts of a good user manual
• Table of contents (two levels if necessary)
• Conventions
• What’s new
• Content
• Appendix
• Index
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 12 of 18
Writing approach
• define audience, goals and content
• assume (almost) nothing about your reader
• put yourself in the reader’s position
• use conventions and a style guide
• be consistent
• avoid jargon
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 13 of 18
Information design approach
• information:– create a hierarchy of importance– create a hierarchy of content
• clear, consistent layout
• user actions paired with outcomes
• create multiple entry points to information
• direct labeling
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 14 of 18
A fundamental tenet
“Good information design is invisible …”
Titus Schleyer, today
… but mistakes in information design might not be visible to you.
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 15 of 18
Usability testing for documentation
• Give users a formal task; use think-out-loud protocol.
• Hand your documentation to a user with a real problem.
• Have developers review your documentation.
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 16 of 18
The idea of “living documentation”
• software lifecycle = documentation lifecycle• changes in software changes in
documentation• linking software to documentation artifacts (e.g.
screens)• usage data, customer input changes in
documentation• on-demand publishing, e.g. online or through
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 17 of 18
Assignment – due 2/23/05
• Write a technote similar to the example on the course Webpage for your assigned task.
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 18 of 18
Resources• Resource lists
– Resources for technical writers (www.writerswrite.com/technical/techlink.htm)– Technical documentation resources (
www.school-for-champions.com/techwriting/resources.htm)– Usernomics consultancy (www.usernomics.com/documentation.html)
• Books – H. Weiss. How To Write Usable User Documentation (2nd Edition). Oryx Press,
1991.– Michael Bremer. Untechnical Writing - How to Write About Technical Subjects
and Products So Anyone Can Understand. UnTechnical Press, 1999.• Short articles:
– Writing software manuals from the middle out (http://www.williamrice.com/content/view/21/32/)
– Better screenshots (www.williamrice.com/content/view/17/32/) – Living documentation: The future of technical writing (
www.poewar.com/articles/living_documentation.htm)