The Society for Technical Communication 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.

The STC Toronto Chapter was founded in 1959 (then the Society of Technical Writers) and is the largest chapter in Canada.

About this Newsletter:

The Wandering Eye
Some Recent Technical Writing Books
by Keith Soltys

• Developing Quality Technical Documentation: A Handbook for Writers and Editors, 2nd edition, Gretchen Hargis and others, IBM Press, 2004, ISBN 0-13-147749-8, 444 pages, $57.99, hardcover
• Read Me First!: A Software Guide for the Computer Industry, Sun Technical Publications, Sun Microsystems Press, 2003, ISBN 0-13-142899-3, 356 pages, $54.99, soft cover
• Word Hacks, Andrew Savikas, O'Reilly Media Inc, 2005, ISBN 0-596-00493-1, 372 pages, $36.95, soft cover
• Office 2003 XML, Evan Lenz, Mary McRae, and Simon St. Laurent, O'Reilly Media Inc., 2004, 567 pages, $57.95, soft cover

This month, I'm going to review some books that have ended up on my desk at work during the last year.

Developing Quality Technical Documentation: A Handbook for Writers and Editors is probably the best book I've read on technical communication since Karen Schriver's Dynamics in Document Design was published in 1997. It gives you a step-by-step process to improve the quality of your writing and your documentation.

The book is divided into three main parts, describing the quality characteristics: easy to use, easy to understand, and easy to find. In each part, there are three chapters further subdividing the quality characteristics; for example 'easy to use' has the chapters: Task Orientation, Accuracy, and Completeness. The chapters' sections are task oriented, providing a list of tasks you can follow to apply the quality characteristics to your writing; for example: 'Write for the intended audience' or 'Focus on the meaning'. Within each section, there's a discussion of the principles, along with numerous examples of applying the quality characteristics to improve writing. The fourth part of the book explains how to apply multiple quality characteristics and how to review information. A series of appendices provide checklists that would help any documentation group improve their writing and review process.

This is a book that would be suitable for almost any writer, from the rank beginner (it would make an ideal textbook for an introductory technical communication course), to the senior writer or documentation manager. There's no substitute for working with a good editor, but Developing Quality Technical Documentation may be the next best thing. If you apply its principles to your writing, you will definitely become a better writer.

Read Me First!: A Software Guide for the Computer Industry started life as the style guide for Sun's technical publication group. It ended up being published as a book and is now in its second edition. It's particularly useful for software-industry technical writers, because there aren't many other published style guides focusing on the computer industry. (Yes, there is the Microsoft Manual of Style, but it's both dated and seriously flawed). As well as the usual advice on punctuation, grammar, and style, there are chapters on how to create links between documents (both print and online), writing about computer interfaces, and how to build a documentation department. If your company doesn't already have its own style guide, you could do a lot worse than to follow this one.

O'Reilly has published Word Hacks, by Andrew Savikas, which collects 100 hacks that let you really get at the internals of the way Word works (or often doesn't). Some are fairly straightforward, like how to get Word to make PDF files without using Acrobat; others are seriously geeky, like how to run Perl from inside VBA. Most of these involve some macro programming; the text of the macros of included (and explained} in the book and to save typing, you can download the macros from the O'Reilly site. Although the title implies that it's a power user's book, if you're new to macro programming in Word, it explains the basics of how to install the macros, most of which will run without any customization. Along the way, you'll learn a lot about how Word works and how you can tweak its default settings to fit the way you want to work.

If you want to get a taste of what's in the book, the O'Reilly site has an article called "Hacking Word" that excerpts five of the hacks from the book, including one that I immediately installed to remove the maddening "Char Char" style aliases from Word documents. It works just fine. This is the best book I've seen about Microsoft Word since Woody Leonhard's Word 97 Annoyances. If you have to use Word for more than the occasional letter or memo, this one is a must purchase.

XML has been on the horizon of technical communication for some time, but it looks like the horizon is finally getting a little closer. One big factor is the addition of XML support to Microsoft Office 2003. The O'Reilly book, Office 2003 XML, is a good introduction to this new aspect of Office. The XML features of Office, and more specifically Microsoft Word, are aimed at interchanging information between Office applications and other programs that are XML-enabled. This book gives a good overview of the XML features of Office and provides examples of some of the things that you can do with it. For those who are new to XML, there are appendices that explain the basics of XML and XSLT. However, if you're looking for something to replace the somewhat dated approach to XML used in structured FrameMaker, you won't find it in Office and this book won't help you.

Keith Soltys has been working as a technical writer for 16 years, and is currently at the Toronto Stock Exchange. He maintains the Internet Resources for Technical Communicators web site and has recently started a weblog. He lives in Pickering with his wife, two children, a cat, and an ever growing collection of Grateful Dead CDs.