Articles>Editing>Documentation http://tc.eserver.org/dir/Articles/Editing/Documentation A listing of the most recently indexed works about Articles and Editing and Documentation in the field of technical communication. en-us Copyright (c) 2005-08 by the EServer. All rights reserved. tclib-editorial@eserver.org (TC Library Editorial Board) webmaster@eserver.org (Geoffrey Sauer) http://tc.eserver.org/images/newlogo.gif Articles>Editing>Documentation http://tc.eserver.org/dir/Articles/Editing/Documentation Writing Great Documentation: You Need an Editor http://tc.eserver.org/35710.html http://tc.eserver.org/35710.html All good writers have a dirty little secret: they’re not really that good at writing. Their editors just make it seem that way. It doesn’t matter how well you’ve mastered the language; nobody, even grammar geeks, gets this stuff right on the first pass. If you really want to produce great documentation, it needs to be edited. Unproductive Review Practices: Why They’re Still Around Even Though People Know Better… http://tc.eserver.org/34910.html http://tc.eserver.org/34910.html I have a theory about why we continually see subject matter expertise for review applied to the task of copy-editing, and why that practice is so hard to change. The theory is built around how we: learn to write, learn to review, and ask for review. Editing Modular Documentation: Some Best Practices http://tc.eserver.org/34350.html http://tc.eserver.org/34350.html The authors have come up with eight guidelines and three concrete suggestions on best practices for editing modular documentation, including ensuring that all topics are standalone, that titles are unique and descriptive, and more. Editing Modular Documentation: Some Best Practices http://tc.eserver.org/32036.html http://tc.eserver.org/32036.html Much has been said about the creation of modular documentation - from content management systems, to information architecture, to delivery forms, to the usability of modular content (content being easier to use, easier to understand, and easier to find), and so on. However, not much has been said about the editing of that content, and what the editor's role is in such an environment. Editing Guidelines for Software Documentation http://tc.eserver.org/30814.html http://tc.eserver.org/30814.html 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. Barriers and Approaches to Reviewing Documentation http://tc.eserver.org/30347.html http://tc.eserver.org/30347.html 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. The Art Of Editing: User's Guides Versus Technical Documents http://tc.eserver.org/30287.html http://tc.eserver.org/30287.html 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. The User Edit Method for Evaluating the Usability of Documentation http://tc.eserver.org/28493.html http://tc.eserver.org/28493.html 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. Editing Your Own Documentation http://tc.eserver.org/21411.html http://tc.eserver.org/21411.html 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!' Adapting Traditional Editing Practices for Online Documentation http://tc.eserver.org/20272.html http://tc.eserver.org/20272.html 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. Writing Shorter Manuals http://tc.eserver.org/20189.html http://tc.eserver.org/20189.html 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. Using Editors Where and When It Counts, Part II: How to Edit Instructions http://tc.eserver.org/20019.html http://tc.eserver.org/20019.html 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. Forget About the Lawyers! First, Let's Kill the Editors! Right? http://tc.eserver.org/10812.html http://tc.eserver.org/10812.html 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?