Writing Software Documentation — A Task-Oriented Approach ... an approach to
software documentation that presents information in chronological order based.
Book Review Writing Software Documentation — A Task-Oriented Approach
Writing Software Documentation A Task-Oriented Approach Thomas T Barker Allyn & Bacon, 1998, ISBN 0-205-19576-8 As its title suggests, this book has two main themes, how to document software and how to do so from a task-oriented perspective. Barker offers the following definition for task orientation: an approach to software documentation that presents information in chronological order based on the user’s workplace sequences. This provides an early indication that rephrasing headings does not make a document task-oriented; documentation has to be based on user and task analysis. The book is divided into fifteen chapters, of which the first seven explain the document development process and the remainder form a document design handbook. The development process chapters explain task-orientation, user analysis, task lists, document planning and writing, useful reviews, usability tests and editing. The design handbook chapters start with aspects specific to task-orientation and move on to pages, screens, language and graphics; these are followed by chapters on three types of writing (tutorials, procedures and reference) and on the design of indexes. The structure of each chapter is unusual, including sections for examples, guidelines, discussion and checklists. These are used to support two main types of readers, those reading to do and those reading to understand. A reader who has read the text in full can easily refer to the guidelines in the course of subsequent work. The structure makes the book easy to read, both sequentially and for reference. It is an innovative approach that uses redundancy in an effective way: presenting the same information in different styles and from different viewpoints helps the reader to retain concepts and relate them to one another. Overall, the design of the book is attractive. There are some rather unusual selections of typefaces and graphic elements in the headings, which may not be to all readers’ tastes, but pages are organised clearly and examples are shown as they would appear in use. The examples are one of the strengths of the book, being both well chosen and clearly explained. They provide ideas for ways to enhance existing documents, even when it is not possible to re-design them with full task-orientation. This book conveys a comprehensive picture of the process of documenting software for users. It analyses aspects in some depth, providing plenty for the experienced author to consider. It succeeds in doing this so clearly that it could also act as an introduction for someone new to technical writing in general or to software documentation in particular. Although the book inevitably covers some of the same ground as standard works such as Schriver’s Dynamics in Document Design and Burnett’s Technical Communication, it is useful to see the theory related directly to software documentation. Of course, a book cannot solve all the problems that authors often face in the workplace. For example, detailed user analysis is out of the question for authors who do not even have access to their users. This book is refreshingly pragmatic about the constraints working authors encounter and, even in environments that are far from ideal, many of the ideas and tips will be of value. Some authors may be able to use the book, with its many examples, as evidence to support their case for developing a new approach to their company’s software documentation. For those of us who have not had as much experience of modern documentation processes as we might like, it at least explains the stages and terminology involved. © Marian Newell, 2000, 2002 NEWELL - PORTER LIMITED
1 of 2 www.newellporter.co.uk
Book Review Writing Software Documentation — A Task-Oriented Approach
About the author Barker teaches two courses at Texas Tech University, Writing Instructional Materials and Writing for the Computer Industry.
© Marian Newell, 2000, 2002 NEWELL - PORTER LIMITED
2 of 2 www.newellporter.co.uk
