Passing the Design Buck

- Gerry Gaffney. June 11, 2002. Drawings by Gina Ellis.

Download 'printer-friendly' PDF version (File size: 74 KB)

An old joke:

Q: How many hardware engineers does it take to fix a problem?
A: None. We'll fix it in the software.

Q: How many software engineers does it take to fix a problem?
A: None. We'll fix it in the documentation.

Q: How many documentation writers does it take to fix the problem?
A: None. The user can work it out.

- Anon

The fragmented user interface

The development of training, documentation and support materials is frequently divorced from the software development process.

This causes several problems.

• A lack of integration between software and the supporting materials. For example, training, documentation and software may use different terms to describe the same thing
• User interface problems are discovered too late to be addressed in the software. Training and documentation must be used, in effect, to 'fix' user interface problems.
• Those producing support materials may resist improvements to the user interface, since those changes will have a knock-on effect on their own production schedules.

This separation of functions also means that the design team are provided with a means of abdicating responsibility. Problems that are best addressed in the user interface layer are off-loaded to be dealt with by people who do not have the capability to address them effectively.

Fix it in the Documentation

Software and website developers often suggest that something is a 'documentation issue'.

Usually they mean that there is some complexity in the user interface that needs to be clarified or explained to the user.

The description of something as a 'documentation issue' is built on two underlying assumptions:

• That users will read the documentation
• That the problem cannot be fixed readily at the user interface layer.

Both of these assumptions are questionable at best.

Certainly there are some people who tend to read documentation, and they may be reasonably well served by a documented explanation or 'fix'. However, there are also many users who tend to avoid the documentation; for them the fix will be ineffective.

Committing any information to the documentation layer entails the certainty that some people will never see that information.

The assumption that the problem cannot be fixed at the user interface may be true. In many instances, however, it is likely to be the result of laziness (developers can't be bothered finding a solution), lack of knowledge (developers do not have the skills to find a solution) or inappropriate scheduling (developers do not have the time to find a solution).

Fix it in the Training

'The Training' is another repository for user interface problems that are considered to be intractable.

The description of something as a 'training issue' is built on two underlying assumptions:

• That users will receive, understand and retain the training
• That the problem cannot be fixed readily at the user interface layer.

We generally find that training is the suggested solution in corporate environments where there exists the theoretical ability to ensure that all users are trained appropriately.

In practice we find that even in the most committed organizations there are many users who do not receive the training at all (because of absence, or because they have inherited a job role from another person), who receive the training at an inappropriate time (for example, weeks or even months prior to the software becoming available), or who have not retained the information imparted during training.

Principles of Documentation

• Include documentation personnel from the beginning of the design phase.
• Provide the minimum amount of documentation.
• Embed documentation in the user interface. For example, providing an adequate label for a field may remove the need to discuss the field in a separate Help file or manual. Replace codes with meaningful terms, rather than referring the user to an explanation of the codes.
• Make steps apparent. Where there are several steps to be undertaken, consider making these steps an explicit part of the user interface. However, avoid forcing users to take a particular path unless there is an overriding business reason for doing so.
• Provide tight integration between documentation and software. Use techniques such as on-screen tips and pointers to relevant information.
• Provide no documentation rather than poor documentation. Poor documentation fails to meet the users' information needs, reinforces negative attitudes to documentation, and reflects badly on the software.
• Test the documentation as part of any usability testing activity.

Principles of Training

• Include training personnel from the beginning of the design phase.
• Provide the appropriate amount of training. Do not overload users with irrelevant information.
• Ensure training is conducted in a timely fashion, immediately before the software is launched or deployed.
• Ensure that all users have access to training.
• Include practical exercises and tasks.
• Integrate training with the software where practicable.
• Provide access to refresher training.
• Provide mentors.
• Test the training.

Download a 'printer-friendly' PDF version of this sheet (File size: 74 KB)

Download Adobe's free Acrobat Reader (TM) for PDF files