Designing Documentation

1
Designing Documentation

• Sheila Webber
• University of Sheffield
• July 2003

2
Outline

• Introduction
• The steps
• Analysis
• Design
• Assembly
• Editing and production
• Maintenance
• Conclusions

3
Introduction

• Why oh why?
• Because if it's not "relevant" they won't use it
• Because some people like paper
• Because it's portable and doesn't block the
  screen
• Because talking paperclips just won't do

4
Graphic http//www.cl.cam.ac.uk/users/afb21/publi
cations/PPIG99.html
http//www.annoyances.org/
http//www.idleworm.com/tch/pclip.shtml
5
Analysis

• Who am I aiming at?
• What do I want them to do?
• Reference tool or tutorial?
• Where will they use it?
• Who writes owns it?
• Is hardcopy the right medium?
• What are the precise objectives?

6
Design

• Structure
• Break into steps
• Don't do detail too early
• Storyboarding
• Bear in mind the production method (authoring
  reproduction/distribution)
• FrameMaker? Other DTP? Word? PPT? Web?

7
Assembly

• Finding their way round
• Style and language
• Layout and typography
• Consistency
• Legibility

8
What is this doing???
9
Editing and production

• Do user testing - and act on it
• At the very least get a critical friend to test
  it
• Best practicable production method
• Balance currency/ usability/ pragmatism
• Make available where most useful, in most useful
  form

10
You have created set 2 which has 28926 items
containing the phrase ice cream
s market(w) share searches for the phrase market
share
11
Maintenance

• Evaluate
• Update
• Revise your overall learning and teaching
  strategy

12
Conclusion

• Examples?
• Practising what I preach??? The problems!
• Closeness to web usability
• Still lots of paper about, and lots of unwieldy
  systems - it's not a redundant art

13
s.webber_at_sheffield.ac.uk

• http//dis.shef.ac.uk/sheila/sw-umbrella.ppt
• http//dis.shef.ac.uk/sheila/sw-umbrella.pdf
• http//ciquest.shef.ac.uk/infolit/

14
Resources 1

• Horton, W. K. (1991) Illustrating computer
  documentation the art of presenting information
  graphically on paper and online. Wiley
• Schriver, K.A. (1994) Dynamics in Document
  Design Creating Texts for Readers. Wiley
• Tufte, E. (1990) Envisioning information.
  Graphics Press. (and his other 2 books)

15
Resources 2

• Techwr-l Technical writers list resources
  http//www.raycomm.com/techwhirl/index.php3
• McMurrey, D. Designing print documentation
  http//www.io.com/tcm/etwr2372/index_online.html
  (Material relating to a class on this topic,
  includes some tutorials and links)