Collaborative Development of Documents
In a growing fraction of my work, I am involved in the collaborative production of documents, using Microsoft Word, PowerPoint, and Excel. Participants in these collaborations often turn out to have limited skill in using the software, compromising the efficiency of the effort and imperiling the quality of the product. Here is a short list of software-related skills to which would-be contributors to such collaborations may wish to make reference.
Let Word do the work. Never type your own numbers for sections, pages, tables, figures, footnotes, or the document version.
After a change, the best way to update all of the Word-maintained fields is to
The Word-maintained cross-references provide an additional benefit for readers who are using their own computers to peruse the document, instead of reading it on paper. Each Word-maintained cross-reference serves as an internal hyperlink, so clicking on the reference moves Word to the target.
Suppress spurious line breaks. Word regards every hyphen character as the legitimate site of a line break, but line breaks are not appropriate when hyphens are being used as minus signs, as parts of drug designators (like "MK-503"), or in other ways unrelated to syllabification. To generate a non-breaking hyphen, type Ctrl-Shift-hyphen. Similarly, spaces usually delimit words, but sometimes they shouldn't be the sites of line breaks either. For example, line breaks are disconcerting when they separate a number from an associated unit designator ("4 mg") or an honorific from a name ("Mr. Smith"). It's nice to be able to use spaces in mathematical formulas without fear of breakage, and it's ugly to have a small word alone as the last line of a paragraph. To generate a non-breaking space, type Ctrl-Shift-space.
Suppress spurious page breaks. To keep a caption from being separated from the figure or table just below, select the caption and check the Keep with next box at Format | Paragraph | Line and Page Breaks. Similarly, to keep a figure or table from being separated from the caption just below, select the figure or the last row of the table and check the same box. To keep a table from being split between pages, select its non-last rows and check the box.
Use section breaks sparingly, if at all. When you're about to start Section 2 of your 12-page document, don't be tempted to insert a Section Break just because you see this option on one of Word's menus. Section doesn't mean what you might think it means. Section breaks are sometimes useful in a very large document, to separate regions of the document that have different pagination. In a textbook, for example, a section break might be used to separate the front matter (title page, acknowledgments, TOC, etc.) from the main text. In documents of lesser magnitude, unnecessary section breaks will make maintenance more difficult. Section breaks will be automatically generated to separate pages that are different in orientation, but they are unlikely to be beneficial in any other use.
Avoid empty paragraphs. When you press the Enter key twice in a row, you generate an empty paragraph. Empty paragraphs are never needed in Word, and they interfere with numbering and with other sorts of document maintenance. For example, a page break should not be allowed to separate a heading from its headed text, but the easy fix (select the heading, then check the Keep with next box at Format | Paragraph | Line and Page Breaks) doesn't work if the true headed text is separated from the heading by an empty paragraph. Also, intrinsic before-paragraph spacing is suppressed for the first paragraph of each page, but an empty paragraph at the top of a page will generate a spurious empty printed line.
Instead of inserting empty paragraphs, get the spacing you want by appropriate formatting of the real paragraphs (Format | Paragraph | Indents and Spacing | Spacing Before/After).
Use figures effectively. Before inserting a figure, crop it to remove white space from the top and bottom. Then end the current paragraph, insert the picture, and immediately select the picture so that you can format it. As noted above, some of the formatting of pictures uses the fact that in Word, a picture is just a special kind of paragraph. To center a picture within the column, for example, you can use the same button that you use for centering any other sort of paragraph.
Other picture formatting in Word uses picture-specific tools. If you right-click on a selected picture, you'll see a menu with two important entries.
Construct readable tables. As elsewhere, it's best to let Word do the work. For example, it's almost always a mistake to have line breaks, tabs, or other manual spacing within a cell. Instead, use extra rows and columns, merging cells as necessary (select the cells, then Table | Merge Cells).
Because each cell of a table is a paragraph unto itself, the cell can generate extra horizontal and vertical space around its text. Such space will generally be unwanted, so whenever you create a new table, it's a good idea to
Similarly, because each cell is a paragraph, it's a fortiori a sentence, and Word wants to capitalize the initial letter in every cell. In most tables, this capitalization is distracting, and you'll need to go back to restore lower case. In a table or elsewhere, you can use Shift-F3 to toggle the selected text among lower case, all capitals, and Initial Capitals.
If the table or some of its cells are annotated (with p-values, explanations of acronyms, or similar footnote material), the annotations should be placed in the table (not just after it), to keep them from being confused with the main text:
Use footnotes to get distractions out of the main text. In many of the documents I collaborate on these days, simple declarative statements are necessarily buttressed with references to supporting material, explanations of how computations were made, p-values, and so on. When these details are parenthesized into the main text, the reader must slalom around them to get the big picture. All of these distracting items should be deported to footnotes.
Use color only when you must. Some readers may have impaired color vision, and many will have access to only a monochrome copy of the document.
Be careful with drug names. Your molecule may originally have been tracked as LC-05271, a derivative of LC-05266. A little later, USAN gave it the generic name lewcarrolline, and somewhere along the way you picked and registered the trade name EatMe. In every use in every document, exactly one of these names is the right one to use.
When LC-05271 is all you have, that's what you must use. As soon as possible, though, you should use lewcarrolline instead. Every time the reader sees LC-05271, he or she will slow up, checking the digits to make sure that this is a reference to LC-05271, and not to LC-05266 or to some other minor character in your story. If your document makes use of figures or references that ineradicably preserve LC-05271, then you need to remind readers of the equivalence in your captions or footnotes.
Generic names are common nouns, so lewcarrolline is right, and Lewcarrolline (except at the beginning of a sentence) is wrong.
Trade names deserve some sort of typographic emphasis, but rendering them in ALL CAPITALS looks too much like shouting. Small capitals (select some text, then Ctrl-Shift-K) are a good compromise. To make the statement "(EatMe is a registered trademark)," you can add the suffix ® to the first occurrence of EatMe in the document. If ® didn't exist, you wouldn't write out "(EatMe is a registered trademark)," more than once in the same document, and, for the same reason, it's redundant to use the ® more than once per document.
Lewcarrolline may be an assigned synonym for LC-05271, but EatMe is not a synonym for lewcarrolline. Especially if the products sold as EatMe are solid oral dosage forms, they probably contain a variety of adjunctive ingredients. In the drug label of EatMe, some statements will describe EatMe (e.g., it is supplied in small cakes), and others will describe lewcarrolline (e.g., it has such-and-such a molecular weight). Don't use one name where the other is correct.
Communicate with your collaborators.
Navigational aids. When discussing a document face-to-face or in teleconference, you'll save a lot of time if you've made Word generate line numbers in a single sequence covering the document (in File | Page Setup | Layout | Line Numbers, check Add line numbering and select Continuous). In the same vein, every page number should be unique; if your appendices need to be independently numbered, then let the pages of each appendix share a distinct prefix, so the document has at most one Page 3, at most one Page B-3, and so on. Similarly, the format of outline numbering should show the complete prefix of every code: readers shouldn't have to flip back through several pages to verify that a paragraph headed "2(c)" is really the 4(A)2(c) they want, and not the irrelevant 7(D)2(c).
Changes and annotations. Word's Track Changes facility (check all the boxes at Tools | Track Changes | Highlight Changes) is useful for simple, non-contentious spelling corrections and for bulk additions or deletions, but it leaves the text unreadable when it's used for more complex changes. Before making one of those more complex changes, turn Track Changes off.
With Track Changes turned off (and often with Track Changes turned on), it's not sufficient to make a change. You need to annotate the change, drawing attention to it and (perhaps) explaining it to your collaborators. Word's Comment facility (Insert | Comment) might seem to be a good vehicle for such annotations, but it isn't. If comments are evident only with yellow highlighting, then they can be read only when the mouse hovers over them. When the document is printed, the comments are printed in a separate section, like endnotes. Don't use Comments.
The best way to annotate non-obvious changes is to insert (or extend) footnotes, optionally using a special color to distinguish these scaffolding footnotes from the true footnotes around them. Annotative footnotes are especially valuable when contentious text is being batted back and forth, or when you've made a change whose purpose may be obscure, but that might have consequences in yet-undeveloped portions of the document. Footnotes are of course visible when the document is printed. If you think your collaborator's change was wrong, don't just change it back. Instead, change it back and add to his or her footnote, saying "<your initials or name>: John had changed this to XXX, arguing <quote John's footnote>, but this would have been misleading because. . . ." The footnote may thus grow for a while, but take heart. Like all survival curves, all such exchanges ultimately converge.
Issues of style. You and your collaborators will probably discover initial disagreements on matters of style. If you accumulate a formal list of your ultimate agreements, then you won't need to revisit the same petty issues multiple times. For example,
Quality control and signoffs. Some parts of the document (data in tables, for example) may need to be checked by people other than the original author. Some authors use footnotes (or Comments; but see the discussion above) to say things like "QCed by Smith," but this is bad practice. Are all of the tables not so tagged waiting for Smith's attention? Also, the insertion of these tags means that quality control will not actually be complete (that is, the document will not be ready for distribution to other than friendly readers) until someone has gone through to remove all the tags.
Parts of the document that need further attention should be specially tagged before they get that attention, not after. Thus, good practice includes suspending a footnote ("Needs QC, probably by Smith") from each needy table at the time the table is created. Then, this footnote (like the other annotations mentioned above) can grow ("Needs QC, probably by Jones. Smith can't tell which is correct, but the numbers in column 3 here don't jibe with those in the text") and finally disappear, (just like other footnotes) as the various authors converge.
Before creating any PowerPoint slides at all, familiarize yourself with PowerPoint's most common (common = frequent and common = vulgar) pitfalls. Having done that, make sure that your slides are numbered (check the Slide number box at View | Header and Footer | Slide and Apply to All ).
Anticipate inserted rows and columns. During the development of every spreadsheet, rows and columns are likely to be inserted, either by you or by a later reader who, for example, needs a new column of annotations or calculated results. Absolute references to columns or rows (e.g., a column header saying "This column is generally identical to Column P") are therefore to be avoided.
Draw a border. Especially in spreadsheets with regions of sparse data, give the reader a positive signal that he or she has come to the last row or column:
Put annotations on the spreadsheet, not in Excel Comments. Excel has a Comment facility (Insert Comment on the menu that pops up when you right-click a cell), but (like the analogous facility in Word, and for the same reasons), it's rarely the best way to annotate the document. Instead, it's better to have one or more columns devoted to row-by-row comments.
Make constants explicit. Instead of using a numerical constant (say, 2.54) in multiple cells,
Sometimes the numerical constant should vary according to some other property of the row (for example, there might be a column showing "M" for men and "F" for women, and another column that should show an assumed body weight of 70 for men and 60 for women). When this happens,
Use color to distinguish different types of cells. The reader should be able to see at a glance
Other classes of cells (for example, those containing imputed data) may also need to be distinguished.
Page revised: 12/14/2013 13:40