Reading :: Writing Software Documentation, 2ed.

Writing Software Documentation: A Task-Oriented Approach (2ed)
By Thomas T. Barker

I've always liked textbooks that present coherent approaches or methodologies, since they provide a framework within which students can work. Even if that framework is deficient, it holds together enough for students to work out ways to improve it. Tommy Barker's book presents a coherent approach, one without obvious deficiencies. I was introduced to it during my time at Texas Tech, where Tommy teaches, and was immediately impressed with how well it holds together and how carefully it leads students through the steps of developing software documentation. So when I committed to teaching a software documentation course this spring, I looked up Tommy's book and was pleased to discover that he had put out a new edition.

The new edition was necessary, of course, given the enormous changes in software documentation since the book was first published. Technical communication has been around a while as a field, but the boom in the 1980s and 1990s was largely driven by the explosive growth of the software market -- and, let's be honest, the importance of making those boxes heavy so people would feel like they were actually buying something. So paper manuals were incredibly important when Tommy wrote the first edition of the book. But in the 2000s, people have become comfortable buying CD-ROMs or just downloading software, and paper documentation is mostly sold in the form of third-party tutorials such as the Dummies manuals. Manufacturers' software documentation comes primarily in the form of online help, documentation on the website, and embedded documentation in the user interface. And let's not forget user forums, both official and unofficial. These changes are huge, and have really changed the landscape.

Tommy's second edition, released in 2002, gets us halfway through the changes above. I hesitate to say that he should already consider a third version, but another update would allow him to better address the question of user-generated documentation and forums, something that is touched upon in the second edition but not addressed to any great extent. The book is still manual-centric, but addresses online help as well. I expect that the solid foundation provided by the book's approach will allow me to build class components for the issue of user communities, though, so that's fine.

One major issue I had with the book has nothing to do with the author: The book's production values, like those of the series as a whole, are low. Allyn & Bacon has put together a fairly solid series here, but the pages look photocopied and the page design varies noticeably from book to book. If Tommy does come out with a third edition, I hope Allyn & Bacon can match the book with the high production values it deserves.