Kurt Ament - Dysfunctional Documents: A 12-Step Recovery Program for User Documentation

Copyright 2020 by Kurt Ament. All rights reserved. No part of this book may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying, recording or by any information storage and retrieval system, without written permission from the author. ISBN 978-3-00-070825-1 ISBN 978-3-00-070826-8 (e-book) Cover art: Adobe Stock www.levels-of-edit.com Also by Kurt Ament: Single Sourcing: Building Modular DocumentationIndexing: A Nuts-and-Bolts Guide for Technical Writersdysfunctionn. Abnormal or impaired functioning of a bodily system or organ Failure to achieve or sustain a behavioral norm or expected condition, as in a social relationship ContentsFiguresTablesForeword 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. TIP:The copyright-free handbook is difficult to find in print, so I have posted an electronic version on my website (www.levels-of-edit.com). Buehler opened her workshop with an unequivocal statement: Editing is a business. TIP:The copyright-free handbook is difficult to find in print, so I have posted an electronic version on my website (www.levels-of-edit.com). 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. Dysfunctional Documents explains how to make all that happen, based on my own hands-on experience at leading companies in science and industry. 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 About this guide This hands-on guide shows you how to use edit types and levels to transform 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 in the process identifies the roles of writers, editors, and managers. You can customize the process, as needed. Purpose This guide has two integrated goals: Immediate success It shows how to diagnose and treat dysfunction in user documentation. Purpose This guide has two integrated goals: Immediate success It shows how to diagnose and treat dysfunction in user documentation.

It explains how writers and editors can work together to solve problems in specific documents and then convert those solutions into writing guidelines. Continuing success It shows how to prevent dysfunction from creeping back into user documentation by refining the edit process. It outlines the specific roles and responsibilities of writers, editors, and managers in improving document quality. Organization This guide is organized as follows: Hitting bottom How to identify common symptoms of team dysfunction, such as failed collaboration, oversight, and guidelines Step 1. Acknowledge problems How to identify acute and chronic problems with new, legacy, merged, and outsourced documentation Step 2. Define edit types How to customize the classic edit types in The Levels of Edit to match the specific needs of your team Step 3.

Define edit levels How to define distinct edit levels, or editing service packages, that can be referenced in edit request forms Step 4. Edit documents How to identify document problems by edit type and distinguish between global and specific problems Step 5. Write edit reports How to develop reports that illustrate problems and solutions with examples from the document being edited Step 6. Evaluate edit reports How to evaluate edit suggestions and identify best practices as potential writing guidelines Step 7. Propose guidelines How to compile potential writing guidelines into proposals and distribute them to team leaders for evaluation Step 8. Evaluate guidelines How to establish a proposal review process, evaluate individual proposals, and verify proposal decisions Step 9.

Publish guidelines How to compile approved guidelines into a style guide and distribute it to all team members Step 10. Enforce guidelines How to explain and illustrate pertinent guidelines in subsequent document edits and reports Step 11. Update guidelines How to implement practical guidelines, repeal impractical guidelines, and establish exceptions and priorities Step 12. Automate guidelines How to identify solutions for automation, set up a cross-functional team, and build guidelines into tools Appendix A. The Levels of Edit Link to an electronic copy of The Levels of Edit as well as screenshots and explanations of key concepts Appendix B. Edit request forms Guidelines for requesting edits as well as samples of corresponding electronic forms Appendix C.

Writing guidelines Writing guidelines, with negative and positive examples, taken from style guides at real companies Appendix D. Roles and responsibilities Roles of writers, editors, and managers in collaboration, oversight, treatment, and prevention The guide also contains a list of references and an index. Hitting bottom User documentation mirrors the teams that develop it. Teams that pull in different directions are incoherent. Incoherent teams develop incoherent, or dysfunctional, documents. The first step in recovery is acknowledgement.