how to create effective documentation
This is a practical guide for designing instructional texts. It describes each stage in the process very thoroughly – from the selection of paper size and page layout, through composition of clear text, to the use of diagrams and illustrations. Although a number of these issues might seem straightforward, what makes James Hartley’s treatment of them interesting is the persuasive psychological reasons given for making one choice rather than another on vocabulary, line length, or paragraph spacing.
The third edition has been produced with the advances in word-processors in mind, and Web users might be particularly interested in the section dealing with electronic text and some of the tips for producing screen layouts which people will actually read. There is a comprehensive analysis of the visual presentation of information – with subtle distinctions noted between pie charts and bar charts.
A couple of chapters dealing with writing for the elderly and those with impaired sight reinforce the psychological importance of good layout and spatial coherence in writing. There are also some interesting details offered en passant – such as the fact that most readers ignore questions posed after instructions, the psychological advantage of the bulleted list, and the fallibility of Flesch Reading Ease scores.
On questionnaire design, it deals with the danger of ambiguity, citing the example of a job application with the question ‘Give previous experience with dates’ which was answered by ‘Moderately successful in the past, but I am now happily married.’ Each chapter has a full bibliography and suggestions for further reading, and on the whole it bears all the hallmarks of work which is now a standard text. No wonder it’s in its third edition.
© Roy Johnson 2001
James Hartley, Designing Instructional Text, London: Kogan Page, (3rd edn) 1994, pp.183 ISBN: 074941037X
More on information design
More on design
More on media
More on web design