A Review of Writing Software Documentation: A Task-Oriented Approach, 2/E

Writing Software DocumentationThomas Barker
NY: Longman, 2003
ISBN 0-321-10328-9    $62.00    pp. 496

Table of Contents
Companion Web Site

Review by Jessica Reyman
Department of Rhetoric, University of Minnesota

 

With the growing number of technical communication programs, there has developed a need for suitable textbooks for undergraduate courses in writing instructions and technical documentation. However, it is difficult to find a text that is

"The book is an excellent example and solid instructional text for courses in technical communication, offering a comprehensive picture of the process of creating software documentation in refreshing depth."

comprehensive enough to use in an upper-level technical communication course, with both adequate coverage of practical application and theoretical depth. In my own teaching, I have had to rely on various sources, including excerpts from technical writing textbooks with more thorough discussions of writing instructions and procedures (Riordan and Pauley; Woolever; Markel); document design texts (Schriver; Kostelnick and Roberts); and books written by technical writing practitioners on usability and documentation (Nielsen, Hackos). The second edition of Thomas Barker’s Writing Software Documentation: A Task-Oriented Approach, from the Allyn and Bacon series in technical communication, combines the strengths of these by more directly addressing writing instruction and documentation. With coverage of both the practical and theoretical issues surrounding software documentation, it serves well as a primary text for any class on procedure writing, for print or online documentation. Barker has written an accessible and complete text for upper-level students interested in a guide for writing successful instructions. Although he identifies his audience as those “preparing for careers in the computer industry” and “engineers, computer scientists, managers, trainers, and usability specialists,” (xxiii) this book is a writing student’s textbook, with an emphasis on theory in addition to practical application that is surprisingly rare in textbooks for advanced technical communication students.
                    As suggested by its title, Writing Software Documentation is about the intersection of two topics: software documentation and task orientation. Barker defines software documentation as “a form of writing for both print and online media that supports the efficient and effective use of software in its intended environment,” and he defines task orientation as “an approach to software documentation that presents information in chronological order based on the user’s workplace sequences” (xxii). Using the term “task-oriented” to describe what others might call user-centered, he sets out to provide an alternative to system-centered approaches to documentation. Barker does not, however, simply offer up another book about usability: he discusses more than how to write usable documentation, arguing for a reconfiguration of the place of the user. This text follows in the footsteps of technorhetoricians like Robert Johnson, who asserts that “[r]efiguring the place of the user within the space of technology can indeed be accomplished through rhetorical means” (33). Arguing for a user-based model of documentation in which the user, in a rhetoricized space, can become an active participant by applying technology for use, Johnson asks writers to situate technology in an authentic situation, and apply it to the tasks and actions users will be performing. Barker’s text relies on this concept, describing an approach to writing documentation in which information is presented in chronological order based on the user’s workplace activities: by integrating a user's real workplace tasks for a specific environment, the resulting documentation can increase user knowledge and capability, and when possible, satisfy the learner's real needs. Writing Software Documentation addresses in a textbook form the complexities of writing about technology without losing the practical elements. Working against ideologies of technological determinism that position technology as a primary causal factor of social change, it applies a theoretical model for examining technology as "value free" to writing instructions. Barker asks writers to consider how software documentation can shift the focus from the technological artifact to the ways that humans choose to use that technology.
                    Writing Software Documentation is divided into three parts: (1) “The Forms of Software Documentation”; (2) “The Process of Software Documentation”; and (3) “The Tools of Software Documentation.” In the first part, Barker identifies three general structures for documentation, and he describes the characteristics and use of each: tutorials, procedures, and reference. The second part includes discussion of the process of writing documentation, from conducting user analyses to
Structure of Chapters
  • How to read this chapter;
  • Examples;
  • Guidelines;
  • Discussion;
  • Checklist;
  • Glossary; and
  • Practice/problem solving.
    • getting reviews and performing usability tests. Barker incorporates a process-based approach with which writing instructors are familiar. The third part addresses the “tools” of documentation, which Barker defines loosely, including an eclectic collection of topics, from document design, to use of graphics, to indexes, to stylistic concerns. These “tools” show writing itself as a technology, as Bolter and Ong (among others) have asserted with attention to context, culture, and change. Each chapter in Barker’s text follow an effective organizational pattern.
                        At the beginning of each chapter, Barker reminds us of how to use this structure based on two levels of experience: the experienced technical writer and those who are new to documentation. If readers desire to apply the content to practical situations, they should read the guidelines, which offer step-by-step advice on how to proceed, and the checklist section, with reminders for applying core principles to ongoing projects. Those looking to start projects or begin to understand concepts of documentation should consult the discussion sections, which addresses key issues related to chapter topics, and also concentrate on the practice/ problem solving sections. Barker’s dual-track structure, including a “Reading-to-Do Track” and a “Reading-to-Understand Track,” reaches the needs of a multivariate audience. These two tracks act complementarily for classroom purposes, offering content for discussion of concepts related to documentation as well as guidance for project-based units, where students complete their own documentation projects.
                        This second edition is reorganized to reflect a more natural learning process, emphasizing writing as a process. The order has been revised to instruct readers on types of documentation before moving on to topics covering the actual writing of it. The design of the book is more usable, with checklists and revised lists and summaries. Another impressive element of the revised text is the inclusion of relevant and helpful annotated examples, including popular Web sites and online help systems from Google and Microsoft, as well as award-winning examples from STC competitions. Barker's companion Web site has also been revised from its largely summary-based original version. The new site is designed to be interactive, including a message board and chat room, though it has not seen much activity to date. The most valuable area of the site is a list of programs that currently lack documentation, and Barker suggests they serve as topics for student work.
                        In Writing Software Documentation, Barker not only describes a user-centered approach to writing instructions and procedures, but provides an example of such a guide through this textbook. The book is an excellent example and solid instructional text for courses in technical communication, offering a comprehensive picture of the process of creating software documentation in refreshing depth.

     

    Works Cited

    Bolter, Jay David. Writing Space: Computers, Hypertext, and the Remediation of Print. Second Edition. Mahwaw, NJ: Lawrence Erlbaum, 2001.

    Hackos, JoAnn T. Managing Your Documentation Projects. NY: John Wiley & Sons, 1994.

    Johnson, Robert R. User-Centered Technology: A Rhetorical Theory for Computers and Other Mundane Artifacts. NY: SUNY P, 1998.

    Kostelnick, Charles and David R. Roberts. Designing Visual Language: Strategies for Professional Communicators. NY: Pearson Allyn & Bacon, 1997.

    Markel, Mike. Technical Communication. 6th edition. NY: Bedford St. Martin's, 2002.

    Nielsen, Jakob. Designing Web Usability: The Practice of Simplicity. NY: New Riders, 1999.

    Ong, Walter J. Orality and Literacy. NY: Routledge, 1988.

    Riordan, Dan and Stephen Pauley. Technical Report Writing Today. 8th edition. NY: Houghton Mifflin, 2001.

    Schriver, Karen. Dynamics in Document Design: Creating Texts for Readers. NY: John Wiley & Sons, 1996.

    Woolever, Kristin R. Writing for the Technical Professions. 2nd edition. NY: Longman, 2001.