Indexing Technical Documents

If a document contains the information that a reader needs, but if the reader cannot find that information, then the document is useless. Worse than useless, it’s a hindrance. If I know that some information is not available, I won’t waste my time looking for it. However, if I think the information is available, and if I can’t find it after a period of fruitless searching, all I will have achieved is frustration.

Mike Unwalla. TechScribe (2004). Articles>Indexing>Technical Editing

Indexing Technical Documents: An Interview with Lori Lathrop

Indexes are as important to your documentation as your documentation is to the product. Just as it would be difficult, if not impossible, for people to use your product without any documentation, it is equally difficult for people to use documentation without a good index.

Vega, Barbara. Writing World (2001). Articles>Indexing>Technical Editing

Indexing Workshop  

Although we all agree on the importance of a good index, many technical writers find themselves in the position of having to produce an index in a short amount of time with no training or experience.

Winsberg, Freya Y. STC Proceedings (1997). Articles>Indexing>Editing

The Influence of Text Factors on Readers  

The objectives of the research study presented here are to increase the discipline's knowledge about reader performance with technical documents, help writers and editors better allocate their efforts, and explore multivariate studies of text variables. For this study, subjects read and recalled one of two technical texts. Their recall protocols were analyzed for syntactic and semantic characteristics. Preliminary results suggest that information has a greater chance of being recalled if it is in clauses, independent clauses, more important idea units, or the first paragraph of the document. Additional results will be discussed at the conference.

Spyridakis, Jan H. and Carol S. Isakson. STC Proceedings (1998). Articles>TC>Editing

Interactive Editing and Revision Exercises

These example exercises are intended to help you better understand how to write paragraphs according to the five patterns of organization listed above. Each example exercise is followed by an assignment that asks you to use the example exercises and the textbook as a guide in writing paragraphs that are clear and well organized.

Dobrin, Sidney I., Christopher J. Keller and Christian R. Weisser. TCTC. Academic>Course Materials>Editing

Internet Resources for Editors  

This month, I’ll depart slightly from my usual topic and focus on onscreen practices that aren’t actual edits—but that support activities such as fact-checking that we must perform while editing. Specifically, I’ll describe how to use the Internet as a research tool to improve the quality of your editing.

Hart, Geoffrey J.S. Intercom (2003). Articles>Editing>Online

Into the 21st Century: The Changing Role of Editors  

The historical perception that defined editors as guardians of the language falls short in describing editors in high-technology environments today. Essential skills for the 21st century require technical editors who can demonstrate sophisticated and extensive tool knowledge, product knowledge, and an appreciation for current professional trends—in addition to being guardians of the language.

Swartz, Michelle A., Gail M. Wilson, Dan Bakely and Barbara S. Muench. STC Proceedings (1996). Articles>Editing

Introduction to Editing and Abstracting

Course goals: to prepare you to communicate effectively, ethically, responsibly, and professionally in a professional environment; to provide you with skills, strategies, and conceptual knowledge to help you understand aspects of editing and abstracting; to help you understand the symbiotic relationships among form and content, and audience and purpose; and to give you practice expressing writing and editing your own work as well as peers' and to improve your own individual communication and management skills.

Tovey, Janice. East Carolina University (2003). Academic>Courses>Editing

Is Anal Retentive Hyphenated?

If you publish something on the Web and you get it wrong, fix it and move on. View the Web as a temporary home for your designs and ideas. If we allow ourselves to become bogged down in a morass of corrective detail, we'll miss the bigger picture and stifle creativity in ways we can't yet imagine.

Shafer, Dan. Builder.com (1998). Design>Information Design>Editing

The Joy of Indexing: How to Make a Good Document Better  

An index is a road map for a document. A good index helps the user find information easily and quickly. It anticipates the user’s needs and provides logical headings and a parallel, consistent structure. Creating an index involves five steps: 1) analyzing the audience; 2) determining the physical appearance and standards of the index; 3) reading and marking the text; 4) producing, editing, and proofing the index; and 5) testing the index for clarity and usability and revising it as necessary.

Gyure, Gloria M.D. and Colleen S. Kelley. STC Proceedings (1996). Articles>Indexing>Editing

"Just-in-Time" Documentation  

Discusses innovative ways to provide notations in electronic documents using Adobe Acrobat, Microsoft Word, and HTML. These methods include inserting text and voice comments, and displaying short messages.

Linderman, R. Ivan. Intercom (2000). Articles>Editing>Online

Keeping Things Consistent When You're the 'Guest' Editor

Consistency is the cornerstone of intelligent editing. In these days of leaner staffs and smaller budgets, however, many organizations don't employ full-time editors and depend on contract or freelance editors to make sure their publications are written in a consistent — and thus coherent — manner.

Goode, Judith. Editorial Eye, The (1996). Articles>Editing>Publishing

Keyboard Shortcuts and Other Tricks  

This column focuses on using a computer to increase the effectiveness (both the productivity and the quality) of editing manuscripts, with an emphasis on tools and techniques rather than issues of grammar and usage.

Hart, Geoffrey J.S. Intercom (2003). Articles>Editing>Online

The Knowledge Editor(SM): Innovative Editorial Solutions to Meet Your Quality Objectives  

This paper represents over 30 years cumulative work experience, as both corporate staff members and as consultants, and shares recommendations for providing highly valuable editorial contributions. The authors also introduce a new concept for innovative editorial methods that meet the technological and productivity challenges facing today’s information design organizations.

Holland, Mary T. and Kristen Sutton. STC Proceedings (2002). Articles>Editing>Collaboration

Knowledge Management - Challenge for Technical Editors

Knowledge management - is it a challenge for technical editors? Shouldn't knowledge management be more than just taken for granted in technical editing? And isn't the technical editor also the knowledge manager, per se?

Sturz, Wolfgang. TC-FORUM (2000). Articles>Knowledge Management>Technical Editing

Learning the Fine Art of Reviewing

If you asked me what the most painful part of being a technical writer is, my answer would be: 'Getting reviews on time. Getting good feedback and inputs on your work.' For me technical writing has been very pleasurable because I hardly got any review comments. My morale has therefore been very high. Project managers, developers and others are so busy trying to come up with good software (read trying to fix all the goof-ups and bugs!) that they usually tend to give documentation lesser importance. User manuals, who reads them anyway? We do not have time for it!

Kamath, Gurudutt R. IT People (2003). Articles>Editing>Collaboration>Technical Writing

Leaving Copyediting for Computing

A copyeditor for a computer publication wants to change careers. She's thinking of taking a few computer language courses with an eye toward moving into UNIX system administration -- a wide-open field. As someone who has changed careers once or twice, I'll offer a coaching session.

Zuchero, John. Editorial Eye, The (2003). Careers>Editing>Programming

Let Editors Edit   

We technician editors need not worry about declining employment if we can show companies the value of the technology of English. If we can demonstrate how editors can make turgid technical authors communicate better with words, sentences, paragraphs, and overall organization, we will be in demand for jobs that are more prestigious and careers that are infinitely more interesting -- because the need is so great.

Bush, Donald W. STC Proceedings (1995). Articles>Editing>Technical Editing

Long-Distance Editing    

Check out seven tips that will help you and your team remain busy and useful when you have extra time or gaps between projects.

Crognale, Heather. Intercom (2008). Articles>Editing>Collaboration>Online

Looking Sharp  

How to get the most out of the Photoshop sharpening controls - complete with show-and-tell examples.

Blatner, David and Steve Roth. Adobe Magazine (1995). Design>Graphic Design>Image Editing>Adobe Photoshop

Loose Ends: Standards and Styles

Several readers have sent me e-mail comments and questions recently that might be of interest to others. (Even Eye readers who don't spend much time on the Web tell us they're interested in picking up this kind of information.)

Ivey, Keith C. Editorial Eye, The (2003). Articles>Style Guides>Editing

Maintenance

The World∆Wide Web is changing; new browsers appear; the language HTML changes; people change jobs and homepages; and writers learn more about their subject.

Degener, Jutta. Technischen Universitat Berlin (1998). Design>Web Design>Editing

Making Technical Reviews More Efficient  

This paper proposes the use of a database to collect and track technical review comments. It discusses the merits of using a database, provides a sample database structure, and describes use of the database in the review process.

Gelb, Janice. STC Proceedings (1999). Articles>Editing>Online

Manuscript Editing: Resources for Writers of Fiction and Nonfiction

Spending time visiting sites and becoming acquainted with Internet resources will, in the long run, save you time, money, and frustration as you learn more about the world of writing and publishing In addition, there's the added benefits of making new friends, sharing ideas, and learning about the fruitful and the fraudulent.

Lotman, Lynda. Manuscriptediting.com. Resources>Editing>Writing

Masters, Slaves, and Infant Mortality: Language Challenges for Technical Editing      

In this article we explore how some contemporary language usage presents challenges for technical editing. Drawing on scholarship in the rhetoric of science and in critical linguistics, we argue that language does affect our perception of reality. Consequently, the language used in some technical documents needs to be reconsidered or even challenged by technical editors. Present textbooks on technical editing do not directly confront this issue, though some scholars have begun to challenge the use of terms such as 'studgun.' We conclude by demonstrating how a critical analysis of metaphors in everyday technical documents would help students question these language choices and draw attention to the consequences of using them.

Graves, Heather Brodie and Roger Graves. Technical Communication Quarterly (1998). Articles>Editing>Biomedical