Developing Quality Technical Information: A Handbook for Writers and Editors

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

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

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.

While I haven't finished reading this yet, I've already found it very informative and useful. I especially like that it provides before and after examples to show how so-so writing can be improved. It should be required reading for any and all engineers or SME tasked with producing their own technical documentation!

IBM sets the bar high here in terms of documentation. One of my top professional reads here.

I've been writing technical documentation for 20+ years, but I was looking for some sort of "standard" to make sure that I'm meeting industry guidelines. This book is exactly the resource for which I was looking.

The go-to resource for any software documentation project. I'm glad it came in hardback; this book is going to get a workout!

Developing Quality Technical Information provides excellent and consistent advice for writers and editors. Anyone who writes, whether a trained technical author or a software developer who must document his or her program design or code, can be considered "a writer". For professional technical authors and editors, this book provides a handy and accessible aide-mémoire. For others, it provides detailed and reasoned guidance in appropriate English usage.The book covers ease of use, ease of understanding, and ease of retrieval of information. It then discusses how to apply the quality characteristics that have been covered in the preceding chapters and how to ensure that those characteristics have been met. Throughout these chapters, extensive "before and after" examples are provided, helping to clarify the points made.Appendixes provide a quality checklist, a definition of who checks which characteristic, and a correlation of quality characteristics and information elements.I have bought many copies of this book, which I have given to systems architects, project planners, programmers, and testers who were required, as part of their job, to write technical information. In doing this, I was being entirely selfish. In a grossly understaffed editorial department, I needed to educate those "authors" in correct and appropriate grammar and punctuation, to help them write more clearly and, thus, reduce the workload on my tiny editorial group. Of all the options available, this excellent book was most likely to succeed.

Very useful resource on this subject.

Adequate