Overview

Title: Writing and Designing Manuals and Warnings, Fifth Edition

Author: Patricia A. Robinson

How I learned about it: A thread in the Technical Writing subreddit

Would I recommend: If you’re interested in technical writing just for software, no. If you’re interested in technical writing for products, particularly with a focus on safety warnings, this seems like a great resource. It took me less than a week to read, so you don’t have to expect to devote a huge amount of time to it.

Book structure & content

To set expectations, Writing and Designing Manuals and Warnings has nothing to do with writing technical documentation for software. Like, absolutely nothing. It’s about what its title says it is: writing and designing [physical product] manuals and warnings.

The book is organized into four parts, with eleven chapters total. The first part, “Product Safety in the 1st Century” is a general overview and introduces concepts such as:

• Manuals serving dual purposes of informing and marketing
• The existence of international standards to guide manual writing, such as ISO 9000 and 14000 series
• “Sophisticated users”
• Hazard analyses

Most of the content is split across the middle two parts. The second part talks about manuals in general, with some focus on writing, but mostly topics like page layout, selection of graphics, and even how to physically print and affix labels to products. The third part entirely devoted to safety warnings, whether they’re written in manuals or attached to products. There’s a comparison of different standards (ANSI Z535.4 and ISO 3864-2) as well as discussion of some government regulations, and also a section on designing valid and reliable “usability tests” for product warnings.

Finally, the last part contains two chapters discussing company culture and organization related to manual writing, including a case study of a product label that the author consulted on. I thought the case study was one of the cooler parts of the book (it starts on page 296).

General comments

So if Writing and Designing Manuals and Warnings is so far removed from software documentation technical writing, why did I read it? Honestly, it was just a lot of fun to read. Also, I had just finished Operating Systems: Three Easy Pieces, and reading something that I didn’t feel obliged to pay deep attention to was a welcome change of pace.

Throughout the book, the author takes you on a dizzying tour of examples, whether it’s a chart of “microwave oven” vs “heavy-duty wrecker” (page 72) or the Safety Data Sheets of Tungsten (page 232), or anywhere in between, and her immense experience in the field is apparent every step of the way. Examples like the development of “Mr. Yuk” because the traditional poison symbol looks too much like the Pittsburgh Pirates’ logo (page 209) are fascinating insights into results of usability testing. There’s enough detail that you actually learn things, but not so much that only a specialist in the field could possibly be interested in the text.

Chapter 3, “Designing a User-Friendly Manual” does have some general writing advice that will apply no matter what field you are writing in, though nearly everything discussed is also mentioned in Developing Quality Technical Information, which is still my “you must absolutely read this” recommendation. One specific thing she brings up that I hadn’t seen recommended before is keeping subjects consistent even when writing paragraph prose: starting on page 93 she provides two passages, one of which conforms to this advice, and one of which doesn’t, and asks the reader which flows more naturally. To be honest, I thought they were pretty similar, but I can see the merit in keeping parallel structure not just in lists of instructions but also in paragraph instructions, and it’s a tip that I’ll attempt to adapt in my documentation.

A few complaints

Nothing related to the content, but I did have a few small issues with the presentation.

Gender pronouns

For the most part, the author uses “he or she,” but there’s a few places in the first couple chapters where she either forgot to revise from an earlier revision or forgot what the convention was or made a typo - I don’t know what happened, but the pronoun used was simply “he,” which I found pretty offputting. I’m very aware of gender pronouns used in books, and my favorite convention is “they,” followed closely by starting with “she” and then alternating between “she” and “he,” but “he or she” is also ok. Incompletely using “he or she” is aggravating. Also, on page 257, she singles out the language “handyman–or woman–” which I felt was super unnecessary. I know this can seem extremely minor, but this kind of language is implicitly unwelcoming and so I’m going to call it out any time I notice it.

Missing page numbers in figures

On page 155, the author says, “If seeing ‘Figure 5.24’ with no explanation is disconcerting, reading a reference to ‘Figure 5.24’ and then being unable to locate it is downright irritating.” And then the book proceeds to put the reader in precisely this position over the next few chapters. On page 233, figure 9.1 is referenced without a page number; it appears on the very next page, but it’s referenced again on page 250, again without page number.

I found this especially frustrating since I’m used to software books that are pretty much always typeset in LaTeX or another language that allows for page numbers to be easily added alongside references to figures at the time of publication, so figures are always accompanied by page numbers; this book probably was not, and so adding page numbers would have been more difficult, but given the explicit callout that one should provide page numbers, I found this unfortunate enough to warrant a callout here.

Ambiguous bullet points

Finally, the bullet point is used interchangebly to mean two things: either it’s just an unordered list of things, or it’s a list of upcoming section topics. I would have liked the latter to use a different symbol; for example, Developing Quality Technical Information used an open square (like an unchecked box) to denote a list of upcoming sections.

Conclusion

Writing and Designing Manuals and Warnings is a practical guide to all aspects of writing physical product manuals with very little advice for technical writers or developers focusing on software/API documentation. Regardless of whether it’s of direct relevance to your career, though, it’s an engaging and interesting book that’s not too much of a time commitment to read - I finished it in under a week. I found it to be a very enjoyable look into a world of documentation I previously knew nothing about!