"The examples are excellent--right on target and easy to understand and adapt. Even those who don't adopt the entire procedure can profit from the parts, but the greatest value will flow to those who adopt the whole." --Carolyn Mulford, senior writer and editor of Writing That Works

"This is also a book that students can keep for their professional libraries because it will increase in its value to them after they leave class and face real life experiences on the job. It is plain enough for them to understand while they are learning, and at the same time comprehensive enough to support them as professionals." --Elizabeth Boling, Instructional Systems Technology, Indiana University

"It practices what it preaches. Its guidelines are understandable and appropriate; its examples clear. It contains exactly what writers and editors need to know. It is the book that I would have written." --Cynthia E. Spellman, Unisys

The #1 guide to excellence in documentation--now completely updated! A systematic, proven approach to creating great documentation

• Thoroughly revised and updated

• More practical examples

• More coverage of topic-based information, search, and internationalization

Direct from IBM's own documentation experts, this is the definitive guide to developing outstanding technical documentation--for the Web and for print. Using extensive before-and-after examples, illustrations, and checklists, the authors show exactly how to create documentation that's easy to find, understand, and use. This edition includes extensive new coverage of topic-based information, simplifying search and retrievability, internationalization, visual effectiveness, and much more.

Coverage includes:

• Focusing on the tasks and topics users care about most

• Saying more with fewer words

• Using organization and other means to deliver faster access to information

• Presenting information in more visually inviting ways

• Improving the effectiveness of your review process

• Learning from example: sample text, screen captures, illustrations, tables, and much more

Whether you're a writer, editor, designer, or reviewer, if you want to create great documentation, this book shows you how!

Amazon.com® Reader Reviews (Ranked by Helpfulness)

Average Amazon.com® Rating:  Based on 19 Ratings

One of the most complete writing style guides available - 2004-09-01
Reviewer Rating:
When I first started reading this book, I was quite impressed at the amount of detail provided in it. Although any style guide will provide a technical writer with most of the information needed to write effective manuals, this book goes into more detail about the "art" of technical writing than any other book I've read.

There is truly a wealth of excellent information in this book. The authors have covered virtually every aspect of writing technical manuals and also for online material, making this an excellent guide to refer to anytime a writing question comes up. From the beginning chapter (Quality technical information), through chapters on Accuracy, Completeness, Clarity, Style, Organization, and Retrievability (to name a few), you can clearly see this book's attention to detail. The book's last chapter (Reviewing, testing, and evaluating technical information) offers tips on doing review cycles, who to involve in them, usability tests, and evaluating the information contained in the manual.

I especially liked the chapter on Retrievability. As the book points out, information doesn't do the reader any good if there isn't a logical way to find it. This chapter points out ways to "facilitate" navigation, by providing a complete index, the proper level of detail in the Table of Contents, even helpful links (for online material).
Another excellent chapter was the one on Style, although clearly each chapter in this book stands out on its own for providing detailed information about the chapter topic.

Another nice feature of this book is that the beginning of each chapter lists the main points (or topics) to be covered, and then summarizes them at the chapter's end. It serves as an excellent reminder of these points and one that can be referred back to.

I found this book to be an excellent reference and recommend it to any technical writer, regardless of their experience level.

Enshrines mechanics of mediocre technical writing - 2007-04-28
Reviewer Rating:
This book is a mixed bag at best, advocating practices that help keep today's technical writing mired in mediocrity. For example: always use the 2nd person; and for heaven's sake don't try to explain anything to people, just tell them what to do! Much of this reads like tips for helping non-writers get by as technical writers, and for making technical writing into a kind of non-writing.

For devotees of the Jackson Pollock school of tech writing (throw lots of vetted statements at the page till they stick) or of the everything-is-a-numbered-list technique, there's probably much that's heartening in this glossy example of bad desktop publishing. (Jeesh, who decreed that tech writers can't learn typography and basic functional layout, or maybe hire someone that does?)

This book is probably ok for anyone writing product assembly manuals, or documenting GUI interfaces (press this, select that... yup second person actually works pretty well there). But for software? Or for anyone struggling to articulate complex ideas or just write a reasonably compact and self-contained conceptual overview (MIA from most tech writing today), there isn't much help here. Maybe it's time we technical writers focused more on good writing per se, on the things that good technical writing shares with effective prose (clarity, precision, range of useful styles, fiction (point of view) or even poetry (compression, effective use of embedded metaphor).

So, yeah, it turns out there're so many other rich directions and ideas for tech writers to pursue. For starters, there're the old standbys: Strunk and White or Wm Zinsser's Writing Well. And any of the wonderful books on prose style by Richard Lanham or perhaps Mark Turner's Clear and Simple as the Truth (which, suprisingly enough, addresses technical writing directly, albeit briefly, offering a number of classical examples). Also just about any of Edward Tufte's books, and by the way, did you catch his 2004 interview in Technical Communications Quarterly? Posted (free) on ET's website. I think it even mentions a time when he consulted with IBM about their tech writing and tried to get them to stop using the second person, and, well...

Best Book I've Found on the Subject! - 2005-11-01
Reviewer Rating:
I've been developing retail software professionally for over 15 years and have been waiting for a book like this one. When I finally discovered the book, I was a little skeptic -- that is until I received the book.

If you are writing help, or any other technical documentation, this *is* the book for you. Coverage of the subject is just right. It's not too overloaded and it's not to light on the subject either.

The only thing missing that I wish they had was recommended templates for different types of documentation. If this book had a CD with samples, it would be worth 2 or 3 times the amount I paid for it.

I highly recommend this book.

best hands-on reference for writing product documentation - 2008-01-27
Reviewer Rating:
This is an essential book if you find yourself writing product documentation and do not have the luxury of an editorial staff or company style guide to tell you right from wrong. It's simple and easy to read, and just tells you what you need to know, nothing more or less. You can go through the whole thing cover to cover in about 12 hours, and then you'll have a pretty good sense of how you should be structuring information. I find the examples useful (if somewhat contrived), and I agree with the book's advice in almost all cases. (I'm a professional tech writer, and I *did* have the luxury of an editor for several years! Regrettably, no more.)

Whether the book "enshrines mediocre technical writing," as someone mentioned, is debatable. The goal of product documentation is simple: Answer the user's question as fast as possible, and get the user productive as fast as possible. There's certainly a place for creativity, but one can't lose sight of the goals, and I think the book's merit is that it focuses persistently on those goals: How do you, the writer, best serve the user's interests?

It's also important to have a guide like this because if you work in a small company, other folks are going to have strong ideas about how the documentation should look. They will want to constantly be inserting feel-good "marketing" messages into the documentation, reminding customers of how wise they were for buying the product. They will have strong opinions about what "concepts" should be stressed over and over. As a writer, you represent the user's interests, and you have to be able to stand up and say "that doesn't work to the user's advantage, and we shouldn't do it like that." If you have a reference to back you up on these points, you'll be much more comfortable taking a strong stand in favor of Usability. And, in the end, that is exactly what any documentation specialist should be standing for. (Yes, I did end on a preposition.)

Excellent text - 2007-05-18
Reviewer Rating:
I purchased this text because I am trying to redirect my career. I have a lot of marketing and public relations in my background, but technical writing is a new area. I found the text easy to read, very informative, and exceptionally helpful. The only reason I gave it four instead of five stars is that it is weighted for web writers. Writing for the web is not a function of the job I am interviewing for, so that information, while interesting, was not particularly helpful for me.

Browse Similar Topics

Top Level Categories:
Software Engineering

Sub-Categories:
Software Engineering > Requirements and Specifications