Business Writing: Resume Writing, Cover Letters, Memos, E-mails, Letters
Writing memos
-
Upload
dentistryinfo -
Category
Documents
-
view
419 -
download
1
description
Transcript of Writing memos
![Page 1: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/1.jpg)
BIOINF 2202: Dental Informatics Seminar
Instructors: Titus Schleyer, Heiko Spallek
Writing technical documentation in IT
![Page 2: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/2.jpg)
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’?
![Page 3: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/3.jpg)
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?
![Page 4: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/4.jpg)
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!
![Page 5: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/5.jpg)
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
![Page 6: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/6.jpg)
Center for Dental Informatics
University of Pittsburgh School of Dental Medicine 6 of 18
Types of documentation
• Tutorial
• General, thematic
• Reference
• How to/FAQ
![Page 7: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/7.jpg)
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?
![Page 8: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/8.jpg)
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!
![Page 9: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/9.jpg)
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
![Page 10: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/10.jpg)
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!
![Page 11: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/11.jpg)
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
![Page 12: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/12.jpg)
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
![Page 13: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/13.jpg)
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
![Page 14: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/14.jpg)
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.
![Page 15: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/15.jpg)
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.
![Page 16: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/16.jpg)
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
![Page 17: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/17.jpg)
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.
![Page 18: Writing memos](https://reader033.fdocuments.net/reader033/viewer/2022061222/548b5b7bb479596c438b4682/html5/thumbnails/18.jpg)
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)