Customer Reviews

Developing Quality Technical Information: A Handbook for Writers and Editors (2nd Edition)

5 star:		(14)
4 star:		(5)
3 star:		(1)
2 star:		(1)
1 star:		(0)

 

 

What a great book! Ms. Hargis has developed a manual that provides readily-accessible and practical information regarding the technical writing process. I actually read (yes, read) this book from cover to cover. Hargis practices what she preaches, by designing a tech writing book with the actual tech writing skills she prescribes. I use this book almost as often as my dictionary and my Microsoft Manual of Style.

One of the most impressive aspects of this book is the vast amount of tech writing examples that can be incorporated into actual documentation. Instead of merely telling the writer what steps to take, Hargis actually SHOWS the writer what to do. How refreshing to read a handbook that actually illustrates tech writing techniques.

The book also provides a multitude of checklists that show the writer the logical progression of the documentation.

A definite must for your stack of books next to your computer.

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.

In spite of the editorial errors in the book (blame IBM Press) and the rather pointless pedantic goings-on in these reviews about the use of the word "quality", this is a most worthwhile manual. Hargis presents her strategy of ensuring that technical documents reflect accuracy, clarity, completeness, concreteness, organization, retrievability, style, task orientation and visual effectiveness. She devotes a chapter to each concept and offers relevant examples to show aspiring tech writers how to apply the concepts to their own work. This is not just a grammar book; it is a well thought out set of tactics that help generate a worthwhile technical document. I'd like to see future editions of this expand into the area of data gathering and instructional system design. Nevertheless, the concepts Hargis describes here are worthwhile, as is this book.

I own many books on technical writing. Almost all of them fall flat in one way or another. Many don't even follow the rules they prescribe. Then there's this book. Superbly organized, consistent, logical, well structured, etc.! Torrents of acolades can get boring, but I hope the point is made; This is a best-of-class effort. Ms. Hargis and her team deliver everything they promise. Page 2 lays out just what to expect.

Buy one, use it, be impressed!

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...

I use many books to assist me in my editing, but this one is the best on my desk. Even if you don't write or edit technical documentation, these pages provide a wealth of information on how to do it right. And, if you do write or edit technical information, this is a great one to have available, no matter what style you use or must conform to. These folks did a great job of breaking down the quality of technical writing into easily digested categories. Recently, I taught the "nine quality characteristics" of the book to the writers I work with and they saw great value in them.

I usually think of my editing and writing books as references, but this one is actually enjoyable to read. Highly recommended!

This is a self-explanatory book for people that have to write information (mostly technical) for others: books, manuals, online info, papers, etc. It has even comments for presentations.

It includes advice when you expect international audience (for example, information in the Web), readers that are non-native speakers of English, color-blind people, etc.

It covers lists, tables, charts, colors, figures, and so on. The book works only with before-and-after examples. But it also has first-, second- and third-revision examples.

About the typos, forgive whoever did them, and take advantage of the excellent contents of the book. I highly recommend it.

STC is an individual membership organization dedicated to advancing the arts and sciences of technical communication. It is the largest organization of its type in the world. Its 25,000 members include technical writers and editors, content developers, documentation specialists, technical illustrators, instructional designers, academics, information architects, usability and human factors professionals, visual designers, Web designers and developers, and translators - anyone whose work makes technical information available to those who need it.

Starting the month of July 2004, DQTI is the featured book on the STC web site: www.stc.org/memberPubs.asp.

This is the best book on this subject that I have found. Her message is clear and she provides concrete examples to reinforce her points. Whether you use this book as a reference or as a text book, you will appreciate it.

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.)