113 pages
February 2021
Levels of Edit
ISBN 978-3-00-068352-7

This hands-on guide shows you how to use levels of edit to turn dysfunctional documents into healthy documents. It provides a flexible 12-step process to diagnose problems, develop treatments, and prevent relapses. And it explains how to create, maintain, enforce, and even automate consensual writing guidelines to keep your documents healthy. Each step identifies the roles of writers, editors, and managers. You can customize the process, as needed.

Review in Publishers Weekly

The following review appeared in Publishers Weekly on May 16, 2022.

Technical communications expert Ament (Indexing: A Nuts-and-Bolts Guide for Technical Writers) offers a clear-eyed, practical, and adaptable guide for technical writers, editors, and publishers and their teams to “to define and use edit types and levels to systematically ratchet up the quality of their user documentation.” That means establishing a process, defining roles and terms, and developing and approving the guidelines that can ensure that the team responsible for the development of technical documents remains focused, connected, and achieves consistent quality. Chief among Ament’s insights: That a team that formally establishes (and updates) its own guidelines is more likely to implement them consistently, taking the documents it produces “to the next level.”

His 12 steps call for clarity on the many different types and levels of edits that user documentation requires, the assigning and scheduling of those different edits, and what editors should offer the team in their reports. Implementing changes, in Ament’s process, doesn’t just come down to an editor’s fiat. Instead, he lays out a process in which writers evaluate and prioritize editors’ suggestions, noting that “If suggestions simply reflect the personal preferences of a particular editor, writers can—and should—ignore them.” Throughout, Ament emphasizes clear communication and evaluation of the process itself. The goal isn’t just the creation of quality documentation; it’s the creation and maintenance of a system that, with care and leadership, can make quality “automatic.”

Ament leads by example by presenting his material in the clearest, most approachable manner, a step-by-step approach laid out with an organizational clarity too often lacking in technical guides, and written in crisp, illuminating prose that on every page exemplifies the results of the process. While targeted to technical writers, Ament’s concise, inviting guide will prove helpful to anyone who leads an editorial team, especially in its scrupulous advice on establishing types of edits and team-specific guidelines.

Takeaway: An illuminating, highly practical guide to establishing an editing process for user documentation.

Great for fans of: Edmond H. Weiss, Marc Achtelig’s Technical Documentation Best Practices.

review in Technical communication

The following review appeared in the August 2021 (Vol. 68, No. 3) issue of “Technical Communication: Journal of the Society for Technical Communication.”

Dysfunctional Documents: A 12-Step Recovery Program for User Documentation is a delightful handbook that takes a practical, step-by-step approach to identifying and correcting the underlying problems in document sets. Kurt Ament takes his inspiration from the venerable Levels of Edit handbook, developed by Robert Van Buren and Mary Fran Buehler for Jet Propulsion Laboratories (JPL) and published by STC, and transforms the principles of editing into a 12-step recovery program.

The first thing you’ll notice about Dysfunctional Documents is the book’s physical size. Its small page format (5 inches by 8 inches) and its thin spine seem miniscule next to traditional technical editing volumes, which tend to be hundreds of pages in length. This smaller format is a feature—not a bug—which makes Dysfunctional Documents less intimidating than other editing texts. It’s about the same size as my iPad mini, which makes it incredibly easy to slip into my bag on my way to my next class or meeting. Its price tag is also significantly smaller than many editing texts, which makes it easier to distribute to your entire team or assign as reading as part of a unit on editing in a technical communication course.

The book’s contents are equally unintimidating and easy to read. Each chapter ranges from three to seven pages and offers concise and actionable advice. Ament, a long-time writer and editor of user documentation, takes a modular approach, breaking each chapter down into manageable topics. Each chapter includes an overview that clearly lays out who is involved at each stage in the recovery process and what their responsibilities are.

The recovery process advocated by Dysfunctional Documents is methodical and practical. Each stage in the recovery process is framed as an actionable step. Concepts described in each step are clearly defined and examples bring the concepts to life. Although the book outlines specific steps toward recovery, the advice is general enough that any technical publications team can apply the advice in ways that suit their documentation libraries and their dysfunctions.

Dysfunctional Documents also includes an appendix that illustrates the types of items writers and editors should consider adding to a styles guide. If your team relies on an outdated style guide—or has no style guide at all—you can use this appendix as an example for creating or revamping your in-house style.

As I read through the book, I found myself nodding my head as I thought about how my own team has been splintered into siloed products, how problems have started cropping up since we began working remotely, and how this recovery program could be applied to my team’s document library. Dysfunctional Documents will be a useful resource for rehabilitating our vast document library.

Michael Opsteegh
Michael Opsteegh is an STC Associate Fellow and a technical writer in the software and financial services industries since 2004. He is a lecturer in the professional writing program at Cal State Long Beach. Michael holds a master’s degree in English and is a Certified Technical Professional Communicator (CPTC).

Foreword

This guide is based on a simple idea: quality can be quantified.

I first encountered this idea in the early 1990s in a certificate program in technical communication co-sponsored by the Society for Technical Communication and the University of California at Los Angeles. Mary Fran Buehler was giving a weekend workshop on The Levels of Edit, the classic editing handbook she co‑authored with Robert Van Buhren in the 1970s at Jet Propulsion Laboratory.

Buehler opened her workshop with an unequivocal statement: “Editing is a business.” She explained that every aspect of the editing process can be quantified. Her conclusion defined my subsequent career: “Quality can be quantified.”

The Levels of Edit identifies nine edit types, which it configures into five edit levels, or editing service packages. In the past half-century, this flexible structure has been customized at numerous companies around the world. The core idea of quantifiable quality has stood the test of time.

Dysfunctional Documents is an attempt to show technical writers, editors, and publication managers how to define and use edit types and levels to systematically ratchet up the quality of their user documentation. It explains how to re‑use the lessons learned in that process to establish best practices, or writing guidelines, to improve the quality of future documents.

It is extremely helpful to illustrate each guideline with negative and positive examples from edited documents. Example-driven guidelines provide a fault-tolerant, scalable foundation for a consensual style guide, which, in turn, serves as the collective memory for writing and editing teams.

For the guidelines to be accepted, they must be put through a formal approval process. Why go to all that trouble? Because writers, editors, and managers are human. They are most likely to accept, follow, and enforce guidelines that they themselves develop, thereby taking their documents to the next level.

Dysfunctional Documents explains how to make all that happen, based on my own hands-on experience at leading companies in science and industry.

Kurt Ament
December 2020

Contents

Foreword

About this guide

Audience
Purpose
Organization

Hitting bottom

Failed collaboration
Failed oversight
Failed guidelines
Learning from failure

Step 1. Acknowledge problems

Identify acute problems
Identify chronic problems

Step 2. Define edit types

Classic edit types
Stand-alone edit types
Modular edit types

Step 3. Define edit levels

Classic edit levels
Stand-alone edit levels
Modular edit levels

Step 4. Edit documents

Identify problems by type
Identify global problems
Identify specific problems

Step 5. Write edit reports

Suggest global solutions
Suggest specific solutions

Step 6. Evaluate edit reports

Evaluate all suggestions
Implement good suggestions
Identify best practices

Step 7. Propose guidelines

Compile proposals
Distribute proposals

Step 8. Evaluate guidelines

Establish a review process
Review individual proposals
Verify proposal decisions

Step 9. Publish guidelines

Compile approved guidelines
Distribute approved guidelines

Step 10. Enforce guidelines

Cite guidelines in edits
Demonstrate guidelines

Step 11. Update guidelines

Implement practical guidelines
Appeal or revise impractical guidelines
Propose new guidelines
Add new guidelines
Change existing guidelines
Establish guideline exceptions

Step 12. Automate guidelines

Identify solutions for automation
Approve automation solutions
Set up a cross-functional team
Build guidelines into tools
Build boilerplate documents

Appendix A. The Levels of Edit

Appendix B. Edit request forms

Quantify expectations
Answer questions
Formalize processes
Sample forms

Appendix C. Writing guidelines

Abbreviations
Capitalization
Headings
Indexes
Person
Sentences
Tense
Voice

Appendix D. Roles and responsibilities

Collaboration roles
Oversight roles
Treatment roles
Prevention roles

References

Index