Writing User Documentation

Course outline

Copyright HCi, 1998

Week 7: Assignment 1 briefing and Usability Exercise

Assignment 1

Your first assignment is worth 50% of the mark for the course. It involves:

• identifying a real organisation where you feel documentation is needed
• talking the management at that organisation into letting you gather information
• gathering enough information to write a documentation plan to AS4258
• writing the plan

You will be assessed on:

• the difficulty of the site that you choose (ie how complex the environment is): 10%
• how completely you describe the situation at the site: 10%
• whether your documentation plan complies with AS4258: 10%
• whether the solution that you propose indicates that you have absorbed the material in the readings, discussions and lectures up to this point: 20%

  Total: 50%

You will not be marked on writing style, layout, grammar, etc, in this assignment (but you will in assignment two).

Choose a problem site that contains at least the following elements:

• written procedures
• more than one audience

Do not choose an off-the-shelf product and describe how to document it; most technical writers in Australia are not involved in this kind of documentation. If you feel that you are an exception (for example, if you are already working in an organisation that develops off the shelf products and documenting them is part of your job) then I will make an exception - but clear it with me first.

I would expect your documentation plan to be at least 20 pages long, but if you can cover what you need to in less, that's fine too.

Usability test exercise

(This makes use of a set of cards, each containing a randomly-generated diagram of boxes, lines and other shapes).

Take one of the cards supplied and write a set of instructions on how to reproduce the diagram on it. Keep the card face down (so that the diagram is hidden from view), and pass your text to the next student, while you receive a sheet of instructions from another student. Draw the diagram described by the sheet of instructions.

When the activity is complete, compare the original diagram with the reproduction. How would you improve the instructions?

Usability test exercise 2

Brief: split into two groups - one will be the subject for the first test, and the other will be the testers. Then the teams will swap.

First test: devise and run a usability test for a web site. I suggest that you decide on some specific information as a target, and measure the time you take to find the specified information.

Second test: devise and run a usability test for a simple software package. I suggest that you target the time you take to perform a multi-step procedure using the documentation as a guide.

First step: write a usability test plan.

Second step: run a usability test using the members of the other team.

Third step: discuss results in a group. Did you test the application or the documentation?