Writing technical documentation in IT

1. Writing technical documentation in IT

2. A fundamental problem “Nobody reads manuals.” Heiko Spallek, always Whose fault is that? The users’ or the writers’?

3. 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?

4. Documentation is a package Parts Whose job is it? • Content • Format • Layout • Language, grammar, style • Usability designer, developer, programmer } communications specialist, technical writer, manager technical writer, editor everyone’s! Writing good documentation is a team effort!

5. Documentation Documentation as part of the software life cycle Programming Specifications Testing Maintenance

6. Types of documentation • Tutorial • General, thematic • Reference • How to/FAQ

7. 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?

8. Audience characteristics • IT skill level • contextual knowledge (e.g. about similar programs) • type • programmer/developer • end user • frequent • occasional • rare • many times: multiple audiences!

9. Some quality aspects of good documentation • concise • complete • up-to-date • free of jargon • well organized • accurate • consistent

10. 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!

11. Parts of a good user manual • Table of contents (two levels if necessary) • Conventions • What’s new • Content • Appendix • Index

12. 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

13. 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

14. A fundamental tenet “Good information design is invisible …” Titus Schleyer, today … but mistakes in information design might not be visible to you.

15. 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.

16. 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 PDF

17. Assignment – due 2/23/05 • Write a technote similar to the example on the course Webpage for your assigned task.

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)