Book Review: Technical Writing 101 by Alan S. Pringle and Sarah S. O’Keefe

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

Links of Note, June 2009: Technical Writing and Communication

It’s Links of Note time, with a look this month, at technical communication. Like marketing, technical communication is evolving in a Web 2.0 world. This post gathers technical communication links about the future of the profession, the future of the Society for Technical Communication, and recent books on timely topics, including the social web for documentation and DITA. Of special interest is a post about core technical writing skills, including information architecture and usability expertise, which are finding their way into high tech copywriting.

Future of Technical Communication

55th Annual Conference – Technical Communication Summit: Session Materials:

If you missed the Society of Technical Communication’s 55th Annual Conference, check out the session materials for the latest tips and trends.

How to Avoid Extinction as a Technical Communicator:

An excellent post, in which I’d Rather Be Writing’s Tom Johnson summarizes a career development workshop where Ellis Pratt (@ellispratt on Twitter), one of the founders of Cherryleaf, argued that technical communicators may eventually become extinct, if they keep using the same methods and formats to deliver information.

Although there will always be a need for people to explain technical material to non-technical people, Ellis said, others may be doing it instead, through the formats users prefer. To survive, technical writers may need to morph into content strategists, managing the information in a systematic way, rather than merely creating it.

Rather than being a “technical communicator,” Ellis believes these roles will more likely be content wrangler, information strategist, user-generated content editor, information assets director, and content use analyst.”

Johnson shares his thoughts on Ellis’ vision of the technical communicator’s evolving role, agreeing that technical communicators have shown little innovation delivering information, in more consumable formats. As an alternative to online help and the long manual, Johnson offers his own success with quick reference guides (anywhere from 1 to 8 pages) and short video tutorials (2 to 4 minutes), as core deliverables. He also mentions his excitement about the potential of new DITA publishing capabilities of Flare 5, because “it means you can push the content out to additional formats more easily.”

You can convert DITA to the Confluence Wiki format, DITA’s XHTML target to WordPress, DITA to InDesign, DITA to web pages, and other formats.

Johnson does not think technical communicators will be displaced by user-generated content.

Except for public, web-based, multi-author, open-source software models, I just don’t see a lot of users contributing help content to the corporate-grown applications (except for the big ones, such as Microsoft Office). Most companies want their help content to look attractive and be accurate, and few project managers believe users can and will fill that gap if you take away the technical writer.

This is the Future of Technical Communication:

Sarah O’Keefe considers the implications of technical communicators monitoring and managing your organization’s communities, via forums and wikis. She asks, “Under what circumstances do you delete information? How do you respond when: information is inaccurate, information is unflattering, or both?”

What if the information is accurate but incomplete?
What if someone describes a way of using your product that could cause injury, even though it’s technically possible? Do you delete the information? Do you add a comment warning of possible injury? What if the reader sees the original post but not the comment?

U.S. Government Acknowledges Technical Writers As Distinct from All Other Writing Professions:

The Society of Technical Communication has been working with the US Department of Labor’s Bureau of Labor Statistics (BLS), since 2007 to update its definition of the technical communications profession. At long last, the Occupational Outlook and Handbook (OOH), published by the US Department of Labor’s BLS, will have an individual report on technical writers, soon to be offically known as technical communication specialist, in the next edition.

From Technical Writer to Marketing Writer:

Given tight budgets, many technical writers are asked to take on marketing writing responsibilities, in addition to their technical documentation deliverables. Janice M. King, herself a former technical writer who transitioned to marketing writing, helps you hone your copywriting skills, with Becoming a High-Tech Marketing Writer. This free guide shows you how to write “powerful promotional materials for high-tech products, services, and companies.”

What Technical Writers Know That Copywriters Don’t:

Janice King, author of Copywriting that Sells High Tech, describes skills in the technical writer’s core set, which copywriters in PR and Marketing departments requires these days, to add interactive content (such as podcasts, webinars, blog posts, and other social media outlets) to traditional marketing doc deliverables (for example, press releases, white papers, and data sheets). For more information, see From Copywriter to Content Developer and the related post, What Technical Writers Can Learn From Copywriters.

The Society of Technical Communication

State of the Society:

“This web page will provide community leaders with information about STC’s current financial challenges to aid in the understanding of the recovery plan that will be presented and discussed during the town hall meetings via conference call.”

From Virtual Town Hall slides, projected 2009 shortfall as high as $1.2M USD, caused by overreliance and recession’s impact, on membership dues and annual conference.

Whither STC?:

In a thoughtful post, Sarah O’Keefe calls on the STC to make some significant changes in the following areas: velocity, community, and openness.

Lifelines to the STC:

I strongly agree with many of Tom Johnson’s 15 points on reforming the STC, which can be summarized here: “Closing off and restricting access to information, with the assumption that doing so increases member value, seems to run contrary to directions the web is heading.” In particular, as a member, I feel my dues should cover more training webinars (which are of value to me, for free, or at a significantly reduced cost.)

Books

Anne Gentle on her Forthcoming Book ~ Conversation and Community: The Social Web for Documentation:

Tom Johnson interviews Anne Gentle about her forthcoming book, Conversation and Community: The Social Web for Documentation, due out, by mid-summer 2009.  Gentle talks about “the future of documentation, the writer’s role, community and documentation, commenting and connecting with users, structured authoring with wikis, and more.” For more information about the book’s release, follow developments at Anne’s blog, JustWriteClick.com.

New Book Aims To Help Newbies Understand DITA Basics:

Scott Abel recommends DITA 101: Fundamentals of DITA for Authors and Managers, from the Rockley Group, as an important work to help technical communicators learn how “to write modular, topic-based, context-independent content using a new breed of authoring tools.” He asserts that learning about DITA is essential for technical communicators to remain competitive:

Gone are the days of the free-for-all approach to creating technical documentation products one-at-a-time using desktop publishing tools. While this technique was the best method possible in the 80s and 90s, today, those who create user manuals, online help systems, and other types of documentation are increasingly expected to take a more formal approach to content creation, utilizing content standards like the Darwin Information Typing Architecture (DITA).

Technical Writing 101, 3rd edition – a review:

This link provides a recent review of Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content, 3rd edition; Alan S. Pringle and Sarah S. O’Keefe, Scriptorium Publishing Services Inc., Research Park Triangle, NC, 2009, ISBN: 978-0-9704733-7-0, 328 p., $20.00 (PDF Download), $35.95 (paper). I am currently reviewing the PDF version of the book and agree that even experienced technical communicators can benefit from its guidelines. Its an ideal resource for college technical writing instructors.

About This Blog: Copyright Information

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

Analyzing Audience Without Direct Access to Customers

Summary: Provides tips on how to analyze audience for user assistance, without direct access to customers. Asks how the advent of Web 2.0, related social media tools, and user-generated content, can help technical communicators have more direct contact, and beyond that, collaboration, with our primary and secondary audiences.

As a technical communicator, I do not often have direct access to my audience. Without a clear understanding of my audience, it’s more difficult to define the purpose of my deliverables, gauge the correct content level, and the best organizational strategy. If this is the case for you, here are some suggested ways to learn more about your audience:

  • Working closely with the Product Manager, who often includes a definition of the product’s intended users in the product requirements.
  • Asking the Product Manager about any anticipated documentation requirements, early on.
  • Speaking with Marketing about customer demographics, segmentation attributes, expertise level, etc.
  • Working closely with QA during the product’s development. As internal users, QA is the best initial customer surrogate and can help you anticipate your audience’s user assistance needs.
  • Working closely with Technical Support representatives, who have first-hand knowledge of the customer’s frequently asked questions and troubleshooting issues.
  • Include Sales Engineers and other Product Implementation Engineers in the review process, as they too, have first-hand knowledge of the customer, and are often champions for the technical documentation.
  • After the documentation is released, directly calling your customers, asking for feedback on the documentation, or using a questionnairre to gain user feedback.
  • Including an e-mail address in the documentation, so customers have a way to provide direct feedback to the documentation team.

What other ways do technical communicators traditionally learn more about the intended audiences for our documentation deliverables? What obstacles do we sometimes face gathering this type of information? Do you see the advent of Web 2.0, related social media tools, and user-generated content, as a way for technical communicators to finally have more direct contact, and beyond that, collaboration, with our primary and secondary audiences? Photo Credit, Intersection Consulting.

About This Blog: Copyright Information

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