How to

Filed under Uncategorized

Editing tips, techniques, and checklists

This section of the website provides “how to” information for editors.

“Use cases” and “user scenarios” explained

This file contains the responses I received to a message I sent on January 21, 2000 to the TECHWR-L and WINHLP-L discussion lists. It was posted on the Techwhirl website for awhile but was removed during a reorganisation of the site. Other people’s comments are included with their permission. Here is my original message: Can …

Alternatives to the paragraph

by Jean Weber Keyword 1 (1), August 1989, pp. 14-16. (Journal of the Australian Society for Technical Communication (NSW) Inc.) “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 …

An example of substantive editing

Some years ago I edited a quarterly magazine for the users of a large Australian computing network. This example (from 1985) is fairly typical of the technical articles I received from department managers. I include here the unedited text and my revised version. The first thing you’ll notice is the ancient technology, but it was …

Audience and document analysis

Before you begin editing a document, try to find out as much as you can about the audience for the document and purpose of the document. Some points to consider: What type of document is it? Why was it written? Who are the audience? Why will they read this document? What does the audience need …

Checkadding

by Irene Wong Back to Editing tables of data. “Checkadding” means adding, subtracting, multiplying, checking percentages and other calculations that may be required to verify the data in front of you. Of course the thought of checkadding a publication of tables is extremely daunting. However, it will probably be the most important edit you can …

Choosing and using help topics

by Jean Hollis Weber This paper describes some common types of help topic and when to use each. See also my paper titled Planning an online help project. Different applications require different mixes of help topics. Choose the topic types that are appropriate for the application you are documenting. Notes: The names given to the …

Deciding what needs to be done

Timing is important Steps to follow when developing an editing plan Analysing the document Establishing editing objectives Prioritising the work Reviewing your plan with the writer or client References Before you begin editing a document, you need to analyse it and plan what needs to be done. The exception is when your job is strictly …

Developing a Departmental Style Guide

This article was originally published around 2000. It is available on the TechWhirL website. Printer-friendly version

Editing an index

This page is a checklist of things to check when editing an index. The first word of an index entry (especially a level 1 entry) should be meaningful, something the reader is likely to be looking for. In most cases, do not start an entry with a verb such as “using” or “displaying.” The reader …

Editing for an international audience

Here are some things to consider when editing for an international audience. Date formats A major problem in international communication is the variation in all-number date formats. Does 3/12/99 mean March 12, 1999 or 3 December 1999? It depends on where you live. Although some dates can’t be mistaken (3/25/99 can’t be the 3rd of …

Editing glossaries

by Jean Hollis Weber Keyword 6 (1), February 1996, p. 21. (Journal of the Australian Society for Technical Communication (NSW) Inc.) Traps for the unwary are common in technical writing. In my 20 years of editing, I’ve seen a lot of things that have slipped by writers and reviewers. Once I edited the glossaries for …

Editing illustrations

Illustrations include photographs, charts and graphs, diagrams, line drawings, and all types of graphics. Graphics and other illustrations can serve a variety of purposes, for example: Attention-getting (capture readers’ interest) Navigation (help readers find the type of information they want, or that applies to them) Clarification (information can often be shown better than it can …

Editing online materials

Presented by Jean Hollis Weberto the Australian Society for Technical Communication (NSW) Conference, 2 November 1996 Terminology: Online Editing online materials Editing anything that is intended to be read on a computer rather than (or in addition to) being read on a paper copy. Online (on screen) editing Making changes to a computer file, rather …

Editing procedures and instructions

Procedural and instructional material is written for a variety of purposes, for example: Training new staff members Recording “the way we do things” in an organisation, as part of a quality process Helping people make a decision, for example on what item they wish to purchase Telling purchasers of a product how to assemble or …

Editing reports and proposals

Businesses, non-profit organizations, government departments, and other groups produce a lot of proposals and reports. This article summarizes some features of reports and proposals that are not the same as books, news items, manuals, magazine articles, memos and many other documents. When preparing to edit a report or proposal, be sure to clarify what you’re …

Editing single-sourced projects

“Single-sourcing” describes situations where one file or database of information contains material that is reused for more than one product or more than one information deliverable. Two common scenarios are: Two or more products having much in common, such as related models of microwave ovens or laptop computers or “light” and “pro” versions of software. …

Editing tables

Tables can be used for different purposes. The most common purpose is to present numerical data. Other data may be in the form of words, phrases or sentences. Some things to look for when editing tables: Is there too much data? If so, is all of the data needed? Can the table be divided into …

Editing tables of data

by Irene Wong “There is a rea1 gulf between the statistical and non-statistica! worlds of ideas, and the statistician often finds it difficult to project his ideas across that gulf. This is perhaps partly his own fault in that his jargon, like all scientific terminology, tends to intensify the difficulties.’ W J Reichmann (1961) Although …

Editing tips

This page is a checklist of things to do when editing your own work. Most of these tips are equally relevant when editing someone else’s work. Edit in small doses, and take frequent breaks. Divide big projects into sections you can edit completely without tiring. Never edit for more than one hour at a time …

Editing Web sites

by Jean Hollis Weber Presented to: Australian Society for Technical Communication (NSW) Conference, 30-31 October 1998 Terminology Web site a group of related HTML files Web page one HTML file (plus its associated image files, if any) Home page (default, index) the first page seen when accessing a Web site Topics covered Audience and purpose …

Gender-neutral technical writing

This article, written around 2000, is available on the TechWhirl website. Printer-friendly version

Hints for developing a table of contents

by Jean Hollis Weber Keyword 3 (3), August 1992, p. 23. (Journal of the Australian Society for Technical Communication (NSW) Inc.) Planning a project before beginning the detailed work is one of the vital steps to success in technical communication. Developing a table of contents is one of the steps in the planning process of …

Parts of a typical statistical table

by Irene Wong Back to Editing tables of data. Note: Hyperlinked numbers refer to explanatory notes at end of table. Grapes: Area, production and yield NSW, 1965-66 to 1989-90 Source: Australian Bureau of Statistics Season 1 Hunter Valley MIA (a) Sunraysia (b) Other NSW Area (c) (hectares) 2 Average 1965-66 to 1969-70 1970-71 to 1974-75 …

Planning an online help project

by Jean Hollis Weber This paper outlines some general principles you need to consider when planning an online help project and creating WinHelp files. See also my paper titled Choosing and using help topics. Some of the tasks described in this paper are the responsibility of the project leader; some are the responsibility of the …

Sample editing checklist

Front Matter Check the publication number. Check the document title. Check the company address. Check the front matter page numbering. Check the printing date. Check the trademark information. Check the copyright information. Check the company phone number and other contact information. Format and Appearance Scan each page for obvious formatting errors. Check the typefaces and …

Stressing what is important in a sentence

In addition to expunging the usual collection of wordy phrases from documents, editors commonly attempt to tighten up writing to make it more direct, clear, and concise. For example, when editing business and technical material, I frequently change sentences containing “it is,” “there is,” and “there are.” Writers often ask me “what was wrong with …

Terminology and spelling for Web-related concepts

Generally speaking, “Web” as a short form of “World Wide Web” is capitalized, with one exception (webmaster). However, your company style may prefer the lower-case version. Web site – two words, capital W. The most common alternative I’ve seen is “website” – one word, lower case w. “Web site” appears to be used more for …

Use of hyphens

This page collects a series of notes from readers of my newsletter, and my responses to those notes, arising from an article in issue 60, 13 May 2002. I thank those who took the time to write and explain *why* some hyphen usage is considered to be correct or incorrect. Here’s the original question and …

Using style sheets

Style sheets supplement the style manual (if there is one). You might also use one to summarize vital information for your own reference or to give to an editor. Record on a style sheet any decisions made for a particular product or publication. For example: What version of English spelling is used (US, UK, Australian) …

What’s wrong with this procedure – answers

In this file, I gave an example of a procedure with problems and invited you to decide what the problems were and now to fix them. Here is my analysis. Problems with the procedure as written The introductory paragraph says the procedure describes how to set up a newly migrated account from three e-mail programs, …

What’s wrong with this procedure?

This procedure is taken from the user guide for Eudora Pro 4.1, an e-mail program. My analysis and one possible revision is given on this page. Importing Settings to Create a New Account (© Qualcomm Inc.) To set up a newly migrated account from Netscape Messenger, Microsoft Outlook Express, and Outlook 98 as an alternate …

Words in several varieties of English

A localisation checklist Revised 31 January 2006. Lots of small edits throughout the list, based on the second round of comments. More feedback welcome! I’m compiling a list of terms in US, UK, Canadian, Australian and Indian English and I need some native speakers of each variety of English to check the list and see …

Working electronically

Some editors, even technical editors, are still marking changes on paper, with someone else typing the editor’s markup into the file. But authors and editors are learning that having the editor type changes and questions directly into the file can be a lot more efficient. Some editors may have the luxury of needing to deal …

How to

Editing tips, techniques, and checklists

Planning and preparing for editing

Editing tips and techniques

Checklists

In this section

My books

My other sites

Related sites

Categories

Archives