The ABCs of Writing a Technical Glossary    

This article identifies and explains format rules, style rules, and lexicographic conventions that have been shown to improve clarity and precision in a technical glossary. Rationale for the rules of language, presentation, and style are examined. The need to allow flexibility in following the rules is discussed in terms of strengthening the technical merit and vitality of the glossary. This article also describes the computer-display techniques and file-management system used in committee to develop U.S. Federal Standard 1037C, Glossary of telecommunication terms, and to display the results both in the meeting room and on the Internet between meetings.

Gray, Evie, William Ingram and Dennis Bodson. Technical Communication Online (1998). Articles>Editing>Technical Editing>Glossary

Alternatives to the Paragraph

'It's all in the manual.' How many times have you heard that - or said it in frustration? After all, when you are the person who wrote the manual, you know that all the answers are there. But time and again readers can't find what they need to know, or don't understand the material. Before you blame the reader, look again at how you've presented the material.

Hollis Weber, Jean. Technical Editors Eyrie (1989). Articles>Editing>Technical Writing

Ask the Indexer: Get Answers to your Indexing Questions from Experienced Technical Indexers  

After brief introductions by 4 panelists who are all members of the Indexing SIG (and experienced indexers and technical writers), we plan to discuss Frequently Asked Questions (FAQs) about indexing, and allow plenty of time for questions.

Bonura, Larry S., Dick Evans, Joan K. Griffitts and Peg Mauer. STC Proceedings (1999). Articles>Indexing>Technical Editing>FAQ

Controlled Languages in Industry

A Controlled Language is a form of language with special restrictions on grammar, style, and vocabulary usage. Typically, the restrictions are placed on technical documents, including instructions, procedures, descriptions, reports, and cautions. One might consider formal written English to be the ultimate Controlled Language: a form of English with restricted word and grammar usages, but a standard too broad and too variable for use in highly technical domains. Whereas formal written English applies to society as a whole, CLs apply to the specialized sublanguages of particular domains.

Wojcik, Richard H. and James E. Hoard. Oregon Health and Science University (2005). Articles>Language>Technical Editing>Controlled Vocabulary

Coping with Wordslaughter and the "Good Enough" Syndrome  

Connatser provides advice for technical editors who aren't granted enough time or money to perform extensive revisions on poorly written documents.

Connatser, Bradford R. Intercom (2004). Articles>Editing>Technical Editing

Developing Indexes

As a technical writer, you'll typically have to create indexes for the print books and for online helps you develop. The type of index we mean here is the classic back-of-book index that shows page numbers on which topics and subtopics occur within the book. An online index is much the same except that you supply hypertext links rather than page numbers.

McMurrey, David A. Illuminati Online (2004). Articles>Editing>Indexing>Technical Writing

Editing Mathematics  

Editing mathematics is like editing a foreign language, with its own conventions, symbols, and rules of grammar. Various typographic rules must be followed exactly since deviations from them change the meaning of the material. Like poetry, placement of the information on the page is important for the meaning. The editor often must be a cryptographer, decoding esoteric handwritten material.

Burgan, Murrie W. STC Proceedings (1997). Articles>Scientific Communication>Technical Editing>Mathematics

Editing Modular Documentation: Some Best Practices

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.

Corbin, Michelle and Yoel Strimling. WritersUA (2008). Articles>Documentation>Technical Writing>Technical Editing

Editing Tables of Data

Tables should allow readers to easily and accurately: see what subject matter and variables are being described; find out absolute values; observe relationships between variables. When you edit a table, it is useful to assess just how well it achieves these ends. Readers will feel confident with your table if they can quickly navigate around and absorb the data.

Hollis Weber, Jean. Technical Editors Eyrie (1999). Articles>Editing>Technical Editing

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

Editing Yourself

Here are some tips that helped me edit my own writing.

Leigh, Heather. Crazy for Words (2007). Articles>Editing>Writing>Technical Writing

Experiencing Technical Writing as Textual Coordination  

This paper describes a recent study of how of four technical writers managed the many artifacts (existing texts and information technologies for producing and manipulating text) that mediated their writing process. The author describes the study and characterizes several recurrent patterns of mediation, including textual reuse, remediation of information, and the staging of texts and software programs. The author describes the value of a repertoire of information technologies to technical writing and argues that technological skill should be considered a core competency of the field.

Slattery, Shaun. STC Proceedings (2005). Articles>Writing>Technical Editing>Technical Writing

The Fault of Vacuity  

I labeled wordiness the most obvious fault in technical writing. In retrospect, I think I was wrong. I believe the greatest fault our writing can have is vacuity, or lack of substance. We too often write words that say nothing.

Bush, Donald W. Intercom (2004). Articles>Editing>Technical Editing>Technical Writing

Grammar Stammer

Don't you think that it is a tragedy that 95 percent of the people who desire to be technical writers have a poor command over the language? I am sure all of us make a mistake or two, once in a while. But to make it in every sentence and paragraph shows utter disrespect for readers.

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

Hockey Sticks and User Assistance: Writing in Times of Resource Constraints

If you have all the resources you need, do the very best job you can in all respects. But if your resources are tight, ask yourself whether you are writing the essential stuff at a level of quality users will notice. Also, ask whether the value of the documentation you are producing aligns with the economic pressures on your company.

Hughes, Michael A. UXmatters (2008). Articles>Writing>Technical Editing

How to Edit for Content  

Editing involves more than just formatting and inserting page numbers. You need to ask, 'How can I improve the communication?'

Bush, Donald W. Intercom (2003). Articles>Editing>Writing>Technical Writing

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

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

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

Mystery Fiction and the Technical Communicator: The Editor's Role  

Technical editors can learn much from editors of mystery fiction. Both orchestrate elaborate game-playing and structuring as they serve as the reader's advocate.

Murphy, Avon J. STC Proceedings (1998). Articles>Editing>Technical Editing

Now That You've Got a Double Agent, What Do You Do With 'Em?  

Having demonstrated the importance of acquiring a double agent for writing projects, we now want to explain the best ways to successfully indoctrinate a double agent. This paper will help you prepare for, orient, train, and become a mentor for a double agent to help make him or her an effective member of your writing team.

Fisher, Judith R., Karen L. Mobley and Michelle M. Wright. STC Proceedings (1994). Articles>Writing>Technical Editing>Collaboration

One Hundred Simple Tech Writing Errors

Here are the 100 writing errors that the author has encountered in his experience. (Followed by the subsequent article 'Ten More Errors in Technical Writing.')

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

The Role of the Editor in the Technical Writing Team

Editing today covers far more than printed materials. In this discussion, I am assuming a technical editor may be required to deal with: printed materials (for example, books, pamphlets, quick reference cards); electronic (for example, online documentation, online help, web pages); video scripts; computer-based training materials. I am also assuming that the audience for the material being edited is not comprised of other technical people; or if it is, the editor is not the person responsible for ensuring the technical accuracy of the material.

Hollis Weber, Jean. Technical Editors Eyrie (2002). Articles>Editing>Collaboration>Technical Writing