Writing User Documentation

Copyright HCi, 1998

Outline and Reading list

Week 1 - Introduction; listening skills exercise

Much of the information that a technical writer needs to work from is available only in other people's heads. One of the key skills of a technical communicator is the ability to get information out of people without resorting to torture.

Week 2 - Audience and task analysis case study discussion

The key technique used in deciding what to write is audience and task analysis, which grew from the same roots as Taylor's value-added model.

Week 3 - Media and tools - presentations

There are many media available for presenting documentation to users - online is only one of them; there many options available for presenting and maintaining online documentation.

Week 4 - Procedures and ISO9000 - lecture

Although in the US (where most technical communication textbooks are written) most technical communicators document shrink-wrapped products, in Australia things are different: we are more often involved in integrating software into the work environment. Quality assurance (as defined by the ISO9000 series of standards) is a key element of this.

Week 5 - AS4258 tutorial

Australian Standard AS4258 -  Software User Documentation Process  - is widely used in this country, and is about to become an international (ISO) standard.

Week 6 - Software development methodologies and document maintenance

User documentation is never developed in isolation from the software development process; in order to understand how this works, you need to know (in broad terms) how software is developed.

Week 7 - Usability testing exercise

Usability testing is the only controlled way to find out whether documentation works.

Week 8 - Assignment 1 due; assignment 2 starts; HTML tutorial

HTML is of course used as the basis for the World Wide Web, but due to recent changes in Microsoft policy, it will soon become the standard for online help across all computer platforms.

Week 9 - Documentation standards; translation - tutorial

Two issues that often come up in large organisations: the use of both in-house, national and international standards for documentation, and the development and management of translated texts.

Week 10 - Copyright case study discussion; OH&S discussion

Two more issues, but this time two that are often more important to the individual than to the organisation. Occupational Health and Safety for technical writers usually means one thing: avoiding RSI.

Week 11- Assignment 2 due; ethics case discussion

Technical writers are neither more nor less ethical than anyone else in our society, but they often face ethical questions not posed to other people.

Week 12 - The tech writing industry - workshop; course feedback session; writing skills test

Many of the students for this course are either looking for a career in technical communications, or to strengthen their current career. To move ahead, you need a map of where you can go.

Reading list