Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects
A book review
by Jeff Staples, Independent Contractor
Andreas Rüping. 2003. Chichester, UK: John Wiley and Sons. [ISBN 0-470-85617-3. 226 pages, including index. $35.00 USD (softcover).]
From the title of his book, I expected that Andreas Rüping intended to help us improve the development of documents about using a software package. Instead, the book discusses developing documents used in the software development process, such as design and functional specifications. And specifically, it describes how to develop these documents in the most effective, lightweight, and agile manner.
The author explains that in a development environment, the more documentation “helps the individuals in a team interact, the more useful documentation becomes, and the easier [documentation] makes it for the team to develop working software” (p. 22).
Although designed for developers, engineers, and programmers, the text can give technical communicators information about how their development counterparts can work more efficiently. And if you have a good working relationship with your subject matter expert (SME), this text can give you helpful information to impart to your SME, the development group, or perhaps the group manager.
The text begins with a brief discussion of agile development and how agile documentation utilizes the agile method principles. For documentation, an agile approach means creating documentation that contains the right information most efficiently.
Rüping presents information in patterns, which “guide you on your way to defining the specific documentation requirements for your individual project, and determining the necessary contents of those documents” (p. 22).
Each chapter presents the information in a problem-solution-discussion structure with each segment of information fitting into an overall pattern for document development. The patterns address the overall issue discussed in each chapter, such as structuring documents so that information is presented effectively.
The titles of the five chapters accurately represent the information presented:
- Chapter 1—Finding the right topics
- Chapter 2—Structuring individual documents
- Chapter 3—Layout and typography
- Chapter 4—Infrastructure and technical organisation
- Chapter 5—Management and quality assurance
The author offers useful information such as “to get the best out of documentation, team members have to spend time on the actual writing, as well as in reflection on what they have written” (p. 169), accompanied by some suggestions for achieving this “solution.” However, surrounding the solution with “problem” and “discussion” text, while reinforcing the material, at the same time buries the true information in the middle and forces you to read all the material. This could hinder you if you want to get in and out as quickly as possible.
The text requires some get-acquainted time. I didn't grasp some of the associations right away. For example, I initially didn't realize that the pattern diagrams (which detail the flow of each chapter) correspond to the problem/solution sections. In fact, I had to go through the chapters several times before this relationship occurred to me.
I find the organization of the book confusing. It is a document that needs to be read sequentially to follow what's being presented. For example, if you don't read the Introduction, where an explanation of a “pattern” is given, you might not fully understand how Rüping is presenting the information.
Thus, Rüping offers a text that advocates creating documentation that is lightweight and agile, yet he presents the information in a text that looks lightweight but is, in truth, anything but agile.