Adapting Traditional Editing Practices for Online Documentation  

Technical editors are possibly best known for their abilities to transform information with format, content, grammatical, and mechanical problems into coherent, concise, understandable, and usable documents. Editors must not only provide such services for the information authors, but they must also understand and support users' needs and expectations. This presentation gives editors an approach to editing online documentation that is rooted in traditional editing practices.

Fink, Bonnie L., Carol Gasser, Jennifer Giordano and Beth A. Williams. STC Proceedings (1998). Articles>Editing>Documentation>Online

Barriers and Approaches to Reviewing Documentation

This article discusses some important issues in implementing a software documentation review process. If you are part of a small development organization and have few reviewer resources available, you may have to improvise techniques for providing the services and procedures suggested here.

Boston Broadside (1997). Articles>Documentation>Editing>Collaboration

Editing Guidelines for Software Documentation

Software documentation can be difficult to review, so it helps to have some editing guidelines to keep you focused. Let's face it; software documentation isn't exactly exciting reading material. But you should be able to complete the job in a productive manner if you keep your coffee cup full and follow the editing guidelines below.

HelpScribe (2008). Articles>Documentation>Editing>Software

Editing Your Own Documentation  

Technical writers sometimes fall into the trap of thinking that the user is stupid. I have often heard technical writers say things like 'well, if the user can't figure that out, maybe he’s in the wrong job!'

Docsymmetry (2003). Articles>Documentation>Editing>Technical Writing

Forget About the Lawyers! First, Let's Kill the Editors! Right?

Some companies and upper management, and even some documentation managers and writers, seem to agree. After all, in today's world of desktop publishing, writers are also typesetters and illustrators -- why not let them be editors as well? They know English. So why not save money, terminate the editors, and let peer editing begin? Or if we do keep some editors, let them be the designers, illustrators, and typesetters. As for language? Forget it! The readers will understand. Besides, who reads documentation anyway?

Sorotskin, Marilee J. Boston Broadside (1991). Articles>Editing>Documentation

The Art Of Editing: User's Guides Versus Technical Documents  

While contemplating topic areas for a presentation at this year's conference, our biggest challenge was the fact that not all technical editors edit the same type of documents. Presentations at STC conferences are heavily concentrated toward user documentation and software instructional manuals. With that as our prime focus, we identified six common elements that we both consider as we edit a document. We then compared our methods of approaching these elements. One of us edits primarily user's guides and procedural manuals; the other edits scientific and technical documents.

Cluff, Susan C. and Sandra R. Marks. STC Proceedings (1994). Articles>Documentation>Editing>Technical Editing

The User Edit Method for Evaluating the Usability of Documentation

A 'user edit' (also known as a 'usability edit') enables you to evaluate the usability of documentation (Schriver, 1991). Participants in a user edit study can either think aloud as they use the documentation to complete tasks or they can mark up the pages of the documentation to indicate where they had problems. The think-aloud protocols or marked-up pages are then reviewed for usability problems. The user edit report lists the problems and recommendations about how to improve the usability of the documentation.

Wilson, Chauncey E. Usability Interface (2006). Articles>Documentation>Editing>Usability

Using Editors Where and When It Counts, Part II: How to Edit Instructions

When I teach courses on editing, I devote about one-third of the sessions to editing instructions. Why? True, there's always a demand for someone who can edit technical manuals or cookbooks, but my real reason is that working on instructions gets you into editorial shape. It hones your ability to keep readers and their needs always in mind, to weigh each word for accuracy, and to be sure that every sentence means what the writer intends.

Waxman, Maron L. Editorial Eye, The (2003). Articles>Documentation>Editing

Writing Shorter Manuals  

Large manuals are expensive to write, produce, and ship, and may make a product seem mare diflcult or complex than it really is. Shorter manuals can decrease telephone support calls, provide a challenge to the writer, and save time and money. With careful planning and preparation, diJjCerent writing and design techniques, and participation in product design, writers can shorten manuals and make users more willing to read them.

Sommerville, Heather M. STC Proceedings (1997). Articles>Documentation>Editing>Writing