Robert R. Fenichel

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.

Word

Let Word do the work.  Never type your own numbers for sections, pages, tables, figures, footnotes, or the document version.  

• If you need to number sections and subsections, decide on a numbering scheme (Format | Bullets and Numbering | Outline Numbered) and use the outline view (View | Outline) to generate the numbers.  To make a cross-reference ("see Section 4.2.1"), don't type the absolute reference.  Instead, insert a Word cross-reference (Insert | Cross-Reference | Heading).

• Every document should have a page footer, with the page number on the right.  To make a cross-reference ("see page 8"), don't type the absolute reference.  Instead, put a Word bookmark at the target text (Insert | Bookmark), and then use a Word cross-reference (Insert | Cross-Reference | Bookmark).

• Don't just type a line of text to serve as a caption, like "Table 3, results."  Instead, insert a Word caption (Insert | Caption | Table).  To make a cross-reference ("see Table 3"), don't type the absolute reference.  Instead, use a Word cross-reference (Insert | Cross-Reference | Table). 

• Similarly, don't just type a line of text to serve as a caption, like "Figure 12, survival curves."  Instead, insert a Word caption (Insert | Caption | Figure).  To make a cross-reference ("as shown in Figure 12"), don't type the absolute reference.  Instead, use a Word cross-reference (Insert | Cross-Reference | Figure). 

• To make a cross-reference to a footnote  ("see footnote 8"), don't type the absolute reference.  Instead,  use a Word cross-reference (Insert | Cross-Reference | Footnote).

• Word won't help you construct an in-paragraph list of (a) this, (b) that, and (c) the other thing, but if you are willing to let each item be a separate paragraph, then Word will again do the work for you:

  • Enter the first item as a separate paragraph, 

  • Select something in it,

  • Give the paragraph a style that includes numbering of the sort you want.  

    • One way to do this is to use Format | Bullets and Numbering | Numbered (or, equivalently, to use the 1__ 2__ 3__ icon on the formatting toolbar), but this method makes an assignment of the form "use the 6th list style," so its results will be unpredictable when the document is moved from your machine to one whose set of available styles is different.  Still, it's quick and easy:  

      • pick the format closest to what you want, 

      • if your desired format is not quite what's offered (e.g., you prefer "a)" to "(a)"), then Customize.

    • A better way is to assign the paragraph's style by choosing from among Word's named list styles.  This method is better because named styles used by a document move with it from machine to machine:

      • pick a named style (Format | Style, make sure that the List selection is "All styles," then pick a named style from the box), or

      • create a new named style (start with Format | Style | New and carry on).

  • Enter the other items, one to a paragraph.

  • To stop generating numbers, select something in your first non-list-item paragraph and then either 

    • toggle the numbering button in the Formatting toolbar,

    •  go back to Format | Bullets and Numbering | Numbered and select None, or

    • assign a non-list style from the list of named styles at Format | Style or in the Formatting toolbar.

To make a cross-reference to a paragraph that Word has numbered (or lettered, as in this example), don't type an absolute reference ("this case is similar to (c)").  Instead, use a Word cross-reference (Insert | Cross-Reference | Numbered item).

Once you've separated the items of a list into paragraphs, some of Word's table-related tools are available.  For example, you can sort the list into alphabetical order by selecting the list and using Table | Sort | Paragraphs.

• The document needs to have an unambiguous version identifier.  The easiest way to do this is to add a timestamp to the left side of the page footer (start with Insert | Field | Date and Time | SaveDate | Options | d-MMM-yy | Add to Field, then change "yy" to "yy HHMM").  If you want the page footer to include the initials of the last editor, you can do that too. Insert | Field | Document Information | User Information | UserInitials usually works, but you may find that it generates the initials of a secretary.  If this is not acceptable, the secretary should go to Tools | Options | User Information, where the Initials generated can be explicitly set to be yours or, indeed, those of an unsuspecting third party.

 After a change, the best way to update all of the Word-maintained fields is to 

• turn off tracking changes (uncheck the Track changes while editing box at Tools | Track Changes | Highlight Changes),

• select something (anything) in the main text, select everything (Ctl-A), and recalculate (F9),

• select something (anything) in a footnote, select everything (Ctl-A), and recalculate (F9) (you will be asked if you really want to do this.  You do),

• select something (anything) in the page footer, select everything (Ctl-A), and recalculate (F9), and

• select something (anything)  in the page header, select everything (Ctl-A), and recalculate (F9).

 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.  

• The Caption entry takes you directly into the Insert | Caption | Figure dialogue, generates the caption immediately below the picture, and along the way sets the picture's paragraph properties as if you had checked the Keep with next box at Format | Paragraph | Line and Page Breaks.  Of course, if your taste runs to having captions above pictures instead of below them, then this won't be what you want.

• The Format Picture entry takes you into a complex dialogue.  In the Layout tab, make sure the picture is set to be printed In line with text.  The other options have only special-purpose uses.

  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 

• select all the cells of the table, 

• go to Format | Paragraph | Indents and Spacing, and then 

• make sure that the Indentation parameters, Spacing Before, and Spacing After are all zero.

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: 

• add a row at the bottom of the table (select all the cells of the last row, then Table | Insert | Rows Below),

• join all of the new cells into one wide cell (Table | Merge Cells), and finally

• put the annotations into the new cell.

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,

• In representing numbers, I favor using a narrow unbreakable space (as is standard in Sweden) as the thousands separator, but you may prefer a comma (as in the U.S.), or a period (as in Germany, where the comma is used as the decimal point).

• I do not favor using thousands separators for numbers smaller than 10 000, but you may prefer to start using them at 1000.

• I favor italicizing foreign phrases, but you might, e.g., prefer "e.g."  to "e.g."  As an ongoing matter, you will need to decide which phrases are no longer to be considered foreign.

• Just as foreign phrases seem to age their way out of italicization, abbreviations (at least in some hands) seem to age their way out of requiring periods.  In particular, I write "E.g., a surgeon addressed as Dr. Smith in the US might in the UK be addressed as Mr. Smith," but you might prefer to write that sentence with up to four fewer periods, or with up to four more.

• I prefer the European style for dates ("23 May 2007"), mainly because it avoids having two adjacent numbers that must be separated by a pauseless comma, but you may prefer the U.S. style ("May 23, 2007").  In many contexts, the sortable numeric style ("2007-05-23") is obviously best, but elsewhere it looks too geeky.

• I believe that a leading zero provides necessary safety  in representing numbers whose absolute value is less than 1 (e.g., 1/2 = 0.5), but you may foolishly prefer to save the smidgen of space (e.g., with 1/2 = .5). 

• In some early hot-type printing processes, most lines had to be left and right justified.  If lines were not justified, things could literally fall apart.  Then we had typewriters, where justification was difficult or impossible.  The first computer word processors justified their output; they didn't need to, but it was a demonstration of prowess.  Justification actually decreases readability, and it occasionally generates distracting rivers of spurious white space.  Justified text now is the mark of an amateur.

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.

PowerPoint

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

Excel

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:  

• Select a rectangular region that starts at the origin and includes every active cell,

• enlarge the region by one row and one column (to allow a new row or new column to be inserted after the last existing one), and

• draw a border on the right and bottom edges of the region (Format | Cells | Border, then pick a line style and click on the right and bottom edges of the Border image), and finally

• drag the row and column headers of the rows and columns just before and after the borders so that those rows and columns are narrow.

 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, 

• generate a separate worksheet (Insert | Worksheet) for constants,

• enter the number in a cell there,

• define (Insert | Name | Define) a name (say, "CmPerInch") for the cell ,

• put a legend (say, "centimeters per inch") in an adjacent cell, and

• back on the worksheet(s) of data, use the name in formulas instead of the number.

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, 

• on the worksheet of constants, create a table whose first column is in alphabetical or numerical order (here, a 2 ´ 2 table with "F" and 60 in the first row, then "M" and 70 in the second row),

• select the table and define a name for it (say, "WeightBySex"), and

• back on the worksheet(s) of data, use a formula instead of the numbers (here, =VLookup(<cell reference>, WeightBySex, 2), where the <cell reference> is to the cell containing the "F" or "M").

Use color to distinguish different types of cells.  The reader should be able to see at a glance 

• which cells contain fixed text (column headers, etc.), 

• which contain actual keyed data, and 

• which contain results that are calculated (=<formula>) or copied (= <cell reference>) from other entries. 

Other classes of cells (for example, those containing imputed data) may also need to be distinguished.

Home

Page revised: 12/14/2013 13:40