As any technical writer knows, answering the obligatory, “What do you do for a living?” question at a party or in any other casual setting is often a conversation stopper. So observe Alan S. Pringle and Sarah S. O’Keefe of Scriptorium Publishing Services, Inc, in the preface to Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content, the 3rd Edition. In good humor, Pringle and O’Keefe supply, what my own experience confirms, is the reaction that usually follows, when you say you’re a technical writer:

• More questions: What’s that?
• Blank stares.
• Minor hostilities: Did you write that worthless online help that came with my wordprocessing software?
  (p. 19).

Book’s Intended Audience

Well, for those who have ever wondered what exactly a technical writer does, or who are thinking about getting started in the field, then this is the right book for you, jam-packed with advice and tools, which even as an experienced technical writer I have found to be quite useful and informative. The book focuses on developing content for computer hardware and software; however, the authors note, “many of the concepts described apply to other forms of technical writing, such as writing about manufacturing environments, medical and pharmaceutical topics, and science” (p. 24).

What’s a technical writer?

The first chapter opens with, “So, What’s a technical writer?” According to Pringle and O’Keefe, “the short definition of a “technical writer” is a person who writes about technical topics. But perhaps a better definition is someone who can explain complicated concepts in clear, easy-to-understand prose.”

A technical writer is really a translator. You start with a complicated piece of technology, and your mission is to explain to a nonexpert how to use that technology (p. 25).

“This deceptively simple mission requires more than just writing ability and understanding of technology.” Although both of those skills are critical, the authors explain, they aren’t enough. Technical writing also requires organizational skills, and detective and people skills.

Four Basic Skill Sets, for Technical Writers

In chapter one, Pringle and O’Keefe outline the four basic skill sets every technical writer needs:

• Knowledge of technology: Though you do not need to be a hardcore techie to be a successful technical writer, you should be “comfortable with and have some basic knowledge about the technology you’ll be documenting,” Pringle and O”Keefe advise (p. 26). Importantly, “you should be willing (or even eager) to learn about new technology, as it develops.”
• Writing ability: “Enormous technical knowledge is no substitute for writing ability.” (p. 29).
• Organizational skills: “To succeed as a technical writer, you need project management and scheduling ability.” (p. 32).
• Detective and people skills: “Often, the problem is not getting information, but identifying what information is relevant” (p. 34).

How Technical Writers Work

In Chapter 2, “The Technical Writing Process,” the authors provide a traditional step-by-step process for developing technical documentation, from the first step of identifying the needed deliverables, to the last step of producing the materials. Here, they also describe the differences between template-based authoring and structured authoring, and how these approaches provide the foundation for single sourcing, which is “the process of using one set of files to create different versions of content and multiple types of output” (p. 45).

I especially enjoyed, and think those just entering the field would greatly benefit from reading, the follow-up thoughts to the formal process description, in which the authors provide a real-world glimpse into how technical writers often work:

During a real-life project, however, you’ll get approximately halfway through step 6 (creating visuals), at which point you’ll discover that the developers have added a slew of new features to the product.

At this point, you’ll go back and document those features, test them against the product, and then discover that the developers also took out a couple of features without telling you. You check with a friendly developer around the corner and discover that those features are just “temporarily disabled;” development found some bugs but expects to correct the problems before the final release.

At this point, you have to make a decision. Do you assume that they will restore the features before the release, or do you delete the content? Or do you hedge your bets by making a copy of the information but removing it from the content for now. Every project is full of happy surprises like these (p. 40).

The authors state that the rest of the book provides more information about how the technical writing process works and offers helpful information about how to handle the inevitable bumps on the road” (p. 40).

Basic and Advanced Technical Writing Topics

I found that Pringle and O’Keefe amply deliver on their promise to provide advice and tools for technical writers, just getting started. In addition to the topics explained above, which describe technical writers’ roles and responsibilities as well as how they get their jobs done, there are all the getting started topics that one would expect in a Technical Writing 101 book, including chapters on doc plans (with suggestions on estimating page counts and hours per page or topic), outlines, the technical writing tool box, tips on getting information, audience analysis, and style considerations.

Writing tips are included in Chapter 7, “Writing Task-Oriented Information,” with related editing advice and checklists in Chapter 9, “The Importance of Being Edited,” and again in “Chapter 11, Final Preparation–production editing.”

Chapter 8, “Visual Communication” and Chapter 10, “Indexing” provide overviews on introductory topics, where even experienced technical writers could use the refresher, as these topics, in my opinion, are too often neglected in our scheduling estimates, or sometimes not as developed as other parts of technical writers’ basic skill sets.

As an experienced technical writer, I was happy to find informative discussions, on these advanced topics, which any technical writer striving to stay abreast of the latest trends driving our field can’t afford to ignore:

• Avoiding International Irritation
• Structured Authoring with XML
• Web 2.0 and Technical Documentation

Recommendation

I taught technical writing for two years, at the university level, and this book would have greatly aided my efforts at the time, providing my students “a real-world guide.” Too many technical writing books focus just on writing mechanics and process, but Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content takes technical writing out of the realm of the classroom and instills in its readers an understanding of the most current tools, trends, and technical writing practices, applicable to a business environment.

When I was just entering the field, this pragmatic book would have helped me to better know what to expect on my first technical writing job. (Indeed, there’s even an appendix called, “Getting Your First Job as a Technical Writer.”) It would have helped further identify what topics and skill sets I would need to continue drilling down on, over the course of my entire career.

On the flip side, though the book does cover traditional writing, organizational, and editing tips, I think that a more in-depth and applied treatment of those topics is still necessary to distinguish technical writers from the many sister disciplines that do technical writing these days, because despite perception, not anyone can do technical writing well.

If I were teaching technical writing today, I would assign liberal portions of Pringle and O’Keefe’s book as background reading, and as a way to launch discussions and related assignments on real-world technical writing topics. As long as our discipline is called technical writing, I’d still also refer to a nuts and bolts guide on writing, like Kristin Woolever’s classic Writing for the Computer Industry, to ensure that my students gained plenty of hands-on writing practice, via  Woolever’s many applied writing exercises. Given how much of today’s communication is visual, I would search for a similar guide, with exercises geared toward building visual literacy and refining online visual presentation skills. I would use the many pragmatic chapters and real-world information from Technical Writing 101 in combination with these other approaches.

As a concluding note to experienced writers who may possibly think they are more advanced than Technical Writing 101— I’d say, think again. The discussions on Structured Authoring with XML, and Web 2.0 and Technical Documentation, are among the most concisely written, best stand-alone explanations that I have seen on these subjects. These sections should be viewed as essential reading for technical writers, both new to the field and experienced. The “Resources” section in the appendix further lists print and online references for technical writers, highlighting some of the best resources in the profession.

I continue to glean some valuable, new nugget, each time I visit Technical Writing 101—so will you.

About This Blog: Copyright Information

Contacting the Author: Content for a Convergent World – Peg Mulligan’s Blog