Home Page
|
|
|
Home Page
iChat
|
This site contains information for students and instructors using Writing Software Documentation, 2ed, by Thomas Barker. This textbook covers the subject of software documentation, which comes in many forms—from the familiar print User’s Manual or Installation Guide to the familiar online help program, Wizards, and embedded Help. I focus exclusively on creating documents (or information products) that help software users learn program features and use them to work productively. Most manuals and help documents that accompany software programs are written by technical writers in the software industry. Students or professionals interested in doing this interesting and challenging work will find in this book a basic foundation in the principles of writing these kinds of documents. What’s New in the Second EditionThis edition improves substantially on the first by the addition and revision of a number of features: · Updated examples. Where possible, examples were selected (many from STC award winners) to reflect current trends in documentation. · Discussions of communicating across cultures. The sections on task orientation and documentation planning contain discussions of techniques for communicating across cultures. · Reorganized Table of Contents. The second edition puts the three main forms of software documentation at the front of the book so that students, and others new to the field, can get a clear idea of the forms before tackling the process of creating them. · Increased emphasis on user orientation. The second edition eliminates an entire chapter on constructing an inventory of the software program (called a “task list”) that fostered a “system” orientation in some documents. · Stronger theoretical basis. This edition focuses on the three-part hierarchy of activity, action, and operation implicit in an “activity theory” approach to work. This approach focuses the user manual and other help documents on activities and actions rather than on operations. · Emphasis on process. The book is divided into Part I: The Forms; Part II: The Process; and Part III: The Tools so readers can clearly see the components of software documentation as a field. · Increased emphasis on utility. The Guidelines in all chapters sections have been revised to reflect a series of easy-to-follow steps. In Part III: The Tools, the chapters include suggestions for planning, executing, and testing the design features discussed in the chapter.
How the book worksThe purpose of this book is to be of practical value to those learning about and producing software documentation products. Therefore, I have tried to balance practical advice with discussions that aim to improve the reader's understanding of how documentation works. The book begins with an introductory chapter that gives the basis for all the guidelines and discussion that follow. The three chapters in Part I are intended to give an overview of the forms of documentation, so that teachers and students can understand what exactly I'm talking about, and get good ideas on which to base the subsequent chapters. At the core of the book, is the process of documenting a software system, starting in Part II with the user analysis and ending with editing and fine tuning. Each of these chapters follows a step-by-step process in the Guidelines section to help you accomplish the tasks in the overall software documentation process (Part II). To accomplish the overall tasks one needs tools—techniques that one learns through experience and applies to the basic user and program information in order to shape the document. These tools are provided in Part III. The chapters in this part cover the basic text and graphics techniques to help the writer do the work and produce software documents that users can apply easily to their work.
|
|
