Punctuation
The purpose of punctuation is to enable the reader to understand a text at first reading, without backtracking. There are various approaches to punctuation �� among others, the aural, the visual, and the syntactic �� and a sometimes bewildering variety of rules and conventions within each, but much of the confusion can be eliminated by applying the first �� and only �� law of punctuation: the reader must never be misled.
One of the nagging little details of punctuation, for example, is the question of which punctuation marks precede the final quotation mark and which follow it. There is an American convention and a British convention and who knows how many variants on each invented by publishers and documentation managers with their own tastes, which they are ready to impose on the writers under their thumbs. Usually it doesn't much matter which convention is being used; it is seldom important to know whether a comma was in the original quotation or has been supplied by the quoting writer. But sometimes quotation marks are used not to set off someone else's words, but to mark off words or characters for special handling by the reader. In such cases, or at any time when it's important that the reader understand exactly what part of the containing sentence is being marked off, only one rule makes sense: if it's part of the quotation, it goes inside the final quotation mark; if not, it goes outside. When a writer tells readers what to enter on a form �� especially a field on a computer screen �� it is essential that the exact sequence of characters to be entered be distinguished from the context in which it is being mentioned, including punctuation supplied by the quoting writer. If I tell a reader:
Never type anything except "Yes" or "No!"
am I telling him to enter the exclamation point when he enters "No"? If you think the answer is obvious, you have some shocks awaiting you; leave the slightest possibility of misunderstanding, and some readers will misinterpret what they read. (Some will misinterpret even if you don't.) In this example, of course, the exclamation point is not part of the string the user is to enter, so the line should read �� assuming that an exclamation point is needed at all �� as:
Never type anything except "Yes" or "No"!
It's sometimes helpful to establish conventions at the very beginning of the document that remove such questions from the domain of punctuation altogether; for example, if your typographical resources permit, you could tell readers that strings of characters they are to type will be shown in italics or in the Courier typeface:
Never type anything except Yes or No! (italics) Never type anything except Yes or No! (Courier)
Never type anything except Yes or No! (Courier)
But such typographical resources are not always available, and not always adequate; not everyone's eyes will catch the difference between one typeface and another, especially if it's just a question of whether some tiny detail �� a final punctuation mark, for example �� is part of the string or not. So rigorously consistent use of quotation marks should, here and elsewhere, be practiced.
Spelling and Grammar Checkers
Microsoft's Word, like most word-processing applications, offers various levels of automatic checking of spelling, grammar, and style. These features are of very mixed quality, and must be used with clear understanding of what they're good for and what they're bad �� sometimes very bad �� for. To begin with, spelling checkers look at each word with only one question in mind: is this a word that's listed in one of the dictionaries I've been supplied with? If the answer is yes, the word is accepted as correct. It doesn't matter whether it's the right word; it's a word, so it passes. The spelling checker will not catch there where their is what the author means, and you can write "the cat was grooming it's coat" without fear of detection. But the spelling checker will catch those misspellings that produce nonsense, and such common faults as repeated words (the at both the end of one line and the beginning of the next). It will also catch extra spaces and many other little mechanicals if you check off the appropriate options before turning it loose on a text.
As for the grammar and style checking that is a further option, my experience is that it is incredibly bad. It has never helped me in the slightest, and has often given me advice that would turn a well-formed sentence into nonsense. I advise you to use it very warily, if at all.
Procedures Presented as Numbered Steps
In technical documentation, it is common to tell a reader how to carry out some task by giving him a step-by-step procedure to perform. When your author does this, you must check the procedure with the user's safety and convenience in mind:
• First, the procedure should be self-contained; in other words, nothing in the instructions should depend on information that is given only elsewhere. Keep in mind that the user may simply have turned to this procedure without reading a single word of the context. If it is necessary for the user to familiarize himself, before executing the procedure, with some passage too long to be incorporated into the procedure description, he must be clearly directed to that passage before he commits himself to anything.
• Second, the procedure must be safely executable by a user who is simply following it step by step, without looking ahead. This means that if the procedure is going to offer alternative ways of achieving some purpose, the fact that there are alternatives must be conveyed to the user before he is invited to perform one of them. If step 6 reads, "Copy this file into the so-and-so folder in order to save it," step 7 should not read, "If you don't have a so-and-so folder, you can just copy it into the root directory." In this case, step 6 should begin, "There are several ways to preserve this file; see substeps (a), (b), and (c) before proceeding." This rule holds even more strongly, of course, if any of the alternatives is dangerous to life, limb, or data; warnings are more helpful if they come before, not just after, someone has fallen into a ditch.
Note that procedures are the subject of a long-standing superstition that has proven difficult to eradicate �� the notion that there is some scientific reason why they should not run longer than seven, or seven plus-or-minus-two, steps. Very few of those who believe in this superstition can cite the study that supposedly supports it; they are often compelled, when challenged, to claim that their position has attained the status of what "everybody knows." In fact, the paper on which the superstition is based is George A. Miller, The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing Information, The Psychological Review 63 (1956), pp. 81�C97.
Professor Miller himself has been trying, ever since he published this paper, to prevent the misuse of its findings, but without great success. If you'd like to see his own words on the subject, see the correspondence between Miller and me; in any event, do not let yourself or your author be imposed on by the claim that "science" has shown that no procedure (or list, or lesson, or whatever) must have more than 7��2 steps or items. The number of steps or items is not for the writer (much less the editor) to determine; it is determined by the procedure or collection in question. If a procedure does seem to be intolerably lengthy, the matter should be taken up with the designer of the procedure, not the writer who is simply trying to present it.
Lists, Bulleted and Numbered
The general rule for choosing between the numbered and the bulleted style is that the numbered is needed when the order in which the items are presented is significant, because (a) their place in that ordering is going to be used as a key in retrieving or referring to them, or (b) the total number of items in the list is significant, and assigning successive numerals to them enables the reader to satisfy himself quickly as to how many there are. The bulleted list is used when neither the position of any item nor the total number of items, is significant, or when numeration is inherent in the listing itself.
If you were naming the fifty states in the order of their admission into the Union, and wanted to be able to refer to "the seventh one admitted," for example, you would use a numbered list; if you just wanted to indicate the relative position of each state in the queue (for example, "just after Kentucky") without caring about its absolute position ("the seventh"), or were just listing the states by name, numbering would be unnecessary. If you were merely listing some examples of Arctic birds without attempting to be exhaustive or attaching any significance to the order in which you named them, numbering would be not just unnecessary but misleading. And if you were listing the kings of England named George, it would be unnecessary to supply numerals to indicate that George I came before George II.
It is important to make it clear to the reader whether a list is exhaustive or selective; one fault that often misleads the reader is a misuse of includes in the introduction to an exhaustive list, when what's meant is consists of or comprises; introduce a list with includes only when it offers just some of the kinds of items it lists. And use no etc. or and so on or et al. after such lists; includes implies that there are more where these came from.
Artwork
Many documents will include what is loosely called artwork �� line drawings, figures, diagrams, and the like. ("Artwork" means graphics supporting a text, as distinguished from plates that are the primary content, as in books on painting and painters, and of which the text is merely supporting material.) This is another category of content that calls for editorial judgment. Many illustrations are inserted not so much because they're needed, or enhance the text, as because the author or the publisher believes in providing "eye candy" �� visual relief for the reader from solid blocks of text. There are publishers and documentation managers who demand an illustration every so many words or pages. The editor who has doubts about the quality of some particular illustration had best begin by determining why it appears at all; if it's there as a matter of such a policy, any criticism of it will have to take that into account.
At the very least, artwork should do no harm; it should not raise doubts in the user's mind that would not have arisen in its absence. The figure should appear very close to the text that it illustrates, and certainly should not require the user to flip back and forth between pages to see both the figure and the text it presumably illuminates. It should use the same terminology for the things that it depicts that is used in the text, and should explain any conventions that it introduces �� for example, what do the arrows going from one box to another imply? Why are some boxes cross-hatched and others not? What part of the entire system does this figure depict?
Tables
If tables extend beyond the page on which they start, make sure the headings are repeated on each new page. It's a further courtesy to the user if each page of a multipage table is clearly identified, in some convenient place, as being the "nth of N parts" so that he knows where he is in the table. If a table cell is deliberately left empty, insert "N/A" or the like to tell the reader that the author didn't just neglect to enter a value there.
The Editing Community
Editing can be a lonely job: for the most part, it's just you and a document on your computer screen or on your desk. So it's important to be aware that you are not alone, even if you're the only editor in your office �� or in town. There is a discussion group or mail-list for editors called Copyediting-L, another for technical writers called TECHWR-L, and one mainly for reference librarians called Stumpers. (I have not given their URLs here, because these things change; use your search engine to find their current URLs.) You should explore them to familiarize yourself with what they have to offer. In particular, the copyediting list offers much help to editors who need advice and information; the regulars in CE-L are always happy to help novices, and among them they have a great deal of experience.
If you subscribe to any of them, you will probably want to subscribe to the digest form, which does not, like an ordinary subscription, send you a separate email message for each individual posting by some member, but only one for each batch of (roughly) five to twenty postings. This not only prevents your "You have mail!" signal from flashing or sounding off every five minutes, but enables you to follow more easily the discussions on whatever topics are currently being dealt with.
Each of these groups forms a little community, which you will quickly become acquainted with. You'll find that some of the regulars are good-tempered and reliable sources of information; others are hypersensitive and liable to start ranting if pressed on one of their tender spots, and so on �� in short, they're human. In some cases, group members who've gotten to know each other from their postings arrange to meet socially, face to face; in the San Francisco Bay area, one member holds regular Summer and Winter Solstice parties for CE-L members at her hilltop home.
Some of the site moderators have their own little idiosyncrasies and b��tes noires, and chastise those posters who offend against what they consider the proprieties either by posting scolding messages on the site, or sending them directly to the offender �� even, in rare cases, by kicking the offender out of the group. But generally the moderators, volunteers who work hard and get little thanks, perform admirably, and deserve more recognition. You will quickly become a dab hand with the Delete button when you see certain names, and certain message topics, on your screen, but you will likewise come to value some contributors highly and get much of value from them. It is also possible, of course, to correspond directly with a poster, bypassing the online message board completely (every posting must contain the address of its author). In fact, it's plainly courteous to do so when the point you want to take up is one that isn't likely to be of interest to anyone else in the group.