Articles>Editing>Technical Editing

Writing Great Documentation: You Need an Editor

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.

Understanding the Value of a Technical Editor

Not all companies understand why it's important for them to have technical editor(s). In fact, many technical editors must justify their existence on a regular basis.

Demonstrating the Value of Editing

Like all other technical communicators, we editors must sometimes struggle to prove our worth to employers. We know our value, and the more clueful of our authors understand, but sometimes it takes a bit more work to convince senior managers that we serve a useful purpose. Managers generally require specific examples, usually supported by hard numbers. In this article, I’ve provided a few random facts and figures that I’ve accumulated over the years that you can share with management.

Creating an Anthology on Editing

Pulling together New Perspectives on Technical Editing, an anthology on editing, was a complex, yet exhilarating experience. The process fell into four stages.

Paper, Screen, or Scissors? Editing on Hard Copy or Soft Copy

The question posted in our discussion list: Should editors edit on hard copy or soft copy? The answer: Yes. Or, it depends. Essentially it is not a matter of should; it is a matter of personal preference and what works best in different situations.

Why the Focus on Review Practices?

improving document review practices is of great concern to many in the biopharmaceutical industry. The reason for this interest can be explained by the following observations which provide some insight as to why review is, or needs to be, a central focus for improving knowledge propagation and dissemination.

Creating Perspective Shadows

Perspective—it’s one of the first things you learn about in any art class. The basic idea is that it’s the way your eye actually sees something, represented on a flat surface such as paper or a monitor. A simple example is drawing a group of objects: You represent an object in the distance by making it smaller, while making objects close to the viewer larger—make sense? In this tutorial, I’m going to show you how to create perspective shadows in Adobe Photoshop CS3. The result is dynamic, but the technique is a breeze!

Jabberwock

Technical editors are constantly required to edit and revise pieces that they don’t fully understand - or even have much information about. That’s part of the game.

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.

Tech Writers, Grammar, and the Prescriptive Attitude

Prescriptive grammar is useful for teaching English as a second language, but it has little value for the practicing writer. Clinging to it may provide emotional security, but only at the expense of making writing harder than it needs to be. The culture-wide devotion to it will not be changed in a moment. But conscientious writers can at least change their own habits, and make life easier for themselves.

Technical Writing's Big Secret

The big secret in technical writing is that most of the harder documents aren't written by the technical writers at all. In fact, many "technical writers" never do any writing at all. Instead, the drafts are written by engineers or marketers. The technical writers perform editorial functions and provide publications services -- copy-editing, layout, review management, and so on.

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.

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.

Editing Yourself

Here are some tips that helped me edit my own 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.

Syntax or Sin Tax: Which Should an Editor Choose?

Proficiency and accuracy are necessary to edit technical communication, but both can be diminished by the conflict of standards and rules from respected sources. This difficulty is further compounded with the differing expectations of audiences, employers, and companies. To resolve potential problems, editors need to refresh their basic skills through workshops, professional journal articles, and the study of updated authoritative sources. Editors then need to address their audience expectations by developing appropriate style guides. By focusing upon the needs of the audience, editors draw upon a variety of sources, some of which may not agree upon the same standards and rules. In such cases, the editor may also break or bend rules to achieve the consistent, accurate communications that best serve the individual audience.

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.

Substantive and Technical Editing: How Far Do You Go?

Authors who cannot answer queries create a barrier to improvement of manuscripts. Some authors resist the idea that their papers might need major changes. Other authors depend on the editor to make changes that the author can and should make. Language barriers can require creative solutions. Also, there is the question of how far to go as an editor in reframing a report (for example, should an editor reframe the purpose of a paper?) and in correcting an author's errors (for example, a claim of a trend when none is shown).

A SIG Transformation: Past, Present, and Future

A recent discussion about the STC's Technical Editing Special Interest Group (TE SIG) provided insights into the evolving role of communities of interest in the Society. At a meeting of the Carolina Chapter's local TE SIG, Diane Feldman, who is the manager of the Society-level SIG, provided members with an update on SIG activities.

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.

Technischer Redakteur

Der Technische Redakteur erstellt und aktualisiert aussagefähige, umsetzbare, verständliche technische Dokumentationen aller Art.

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.

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.

Substantive Editing: With an Eye on the User

This workshop focuses on substantive editing with workshop materials that show fast and easy ways to analyze a piece of writing, especially writing that needs the concentrated effort of both the editor and the writer to turn it into a usable document. The workshop is practical in its focus providing tips, checklists, and techniques for approaching material that needs a heavy substantive edit.

Seven Discrete Principles for Content Editing

One of many lessons I learned in 30 years of Technical Editing was to separate myself from the crowd by learning to edit technical content, using seven reader-oriented techniques.

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.

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.

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.

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?

Technical Translation: Craft, Not Commodity

Describes the work of translators and suggests strategies buyers can use to find the best translator for their needs.

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.

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!

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.')

Ten More Errors in Technical Writing

So, well, here are 10 more errors. This time we will focus on grammar and punctuation. Most of these are simplistic and obvious. But then they are too common. As usual, I have slipped in some content for the advanced writers too. (This article is a follow-up to 'One Hundred Simple Tech Writing Errors .)

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.

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.

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.

Working Electronically

Editors need to know some basic techniques for dealing with files if they are going to be editing them electronically. These techniques apply to files in any format, but exactly what you do depends on which word-processor, desktop publishing program, help authoring system, or other software you are using.

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!'

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.

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.

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.

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.

Technical Editors: Are We Are Own Worst Enemies? Strategies For Working With Authors

The authors explore two studies of cognitive assessments, the Myers Briggs Type Indicator and Boundary Spanning of technical communicators, give readers an opportunity to score themselves, and then they argue that knowing the cognitive differences between technical communicators and the authors they edit can help them improve working relationships with authors. When copyediting, they suggest making suggestions rather than dictates; providing rationale for suggestions; basing suggested changes on style guides, standard references and communication research; and using a levels- of-edit approach.

Situational Editing: A Rhetorical Approach for the Technical Editor

Argues that the rhetorical approach to communication considers situations individually and is necessary for technical editors because their work comprises a series of individual rhetorical decisions. Proposes a rhetorical theory of technical editing.

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.

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?'

The Technical Editor and Document Databases: What the Future May Hold

Technical editors ensure a document communicates with the reader. With XML, active server pages, and dynamic document creation, Web pages are no longer simple hand-crafted text objects, but dynamic groupings of text assembled moments before the reader views the page. With dynamic documents, high-level editing tasks will be, at best, vaguely defined during text creation. To maximize the information content, future technical editors require tighter control over information consistency and content.