38
SAMPLE EFTPS Writing Style Guide Electronic Federal Tax Payment System Maggie Bathory | First Data USA Version 1.0
SAMPLE
EFTPS Writing Style Guide Electronic Federal Tax Payment System
Maggie Bathory | First Data USA
Version 1.0
April 2016
i
Revision Log
This document is controlled through the Document Management Process. To verify the document is the current version in use, contact the EFTPS Technical Writer.
Revision Date Version Editor Name Comments
May 2016 1.0 Maggie Bathory Create new document
April 2016
ii
References
The University of Chicago Press. “The Chicago Manual of Style.” Sixteenth edition. Library of Congress, 2010
First Data Corporate. “First Data Writing Style Guide.” Internal document, 2016.
iii
Table of Contents
1 Introduction ........................................................................................................................................ 1
2 Quick Start Guide ................................................................................................................................ 2
2.1 Professional Voice Do’s and Don’ts ............................................................................................. 2
2.2 Punctuation Do’s and Don’ts ....................................................................................................... 4
2.3 Common EFTPS Client, Project, and Products ............................................................................. 5
3 EFTPS Style Sheet ................................................................................................................................ 6
3.1 Overview ..................................................................................................................................... 6
3.2 Styles ........................................................................................................................................... 6
3.2.1 Style Conventions ................................................................................................................ 6
3.2.2 Headings.............................................................................................................................. 9
4 PowerPoint Deck Style Conventions ................................................................................................. 10
5 Document Parts ................................................................................................................................ 14
5.1 Introduction .............................................................................................................................. 14
5.2 Sensitive but Unclassified.......................................................................................................... 14
5.3 Page Numbers ........................................................................................................................... 14
5.4 Covers and Home Pages ............................................................................................................ 14
5.5 Front Matter ............................................................................................................................. 15
5.6 Hyperlinks ................................................................................................................................. 15
5.7 Tables and Illustrations ............................................................................................................. 15
5.8 Back Matter............................................................................................................................... 16
5.8.1 Appendixes ........................................................................................................................ 16
5.8.2 Chronology ........................................................................................................................ 16
5.8.3 Endnotes ........................................................................................................................... 16
5.8.4 Glossary ............................................................................................................................. 16
5.8.5 Bibliography or Reference List........................................................................................... 17
5.9 Version Control and Material not Available in Print .................................................................. 17
5.9.1 Corrections to Documents ................................................................................................ 17
5.9.2 Drafts and Near Final Drafts .............................................................................................. 17
5.10 Design and Style ........................................................................................................................ 17
April 2016
iv
6 Web-based Publications ................................................................................................................... 18
6.1 Functional Features ................................................................................................................... 18
6.2 Navigation— the Primary Way to Organize Content for Web-based Publications .................... 18
6.3 Hyperlinks ................................................................................................................................. 19
6.4 Front Matter ............................................................................................................................. 19
6.5 Folios, Running Heads, and Other “Print” Elements ................................................................. 20
6.6 Indexes, Notes, and Other Back Matter .................................................................................... 20
7 Document Preparation, Editing, and Proofreading ........................................................................... 21
7.1 Formatting ................................................................................................................................ 21
7.1.1 Illustrations and Tables ..................................................................................................... 22
7.1.2 Bibliography and References ............................................................................................. 23
7.1.3 Cross-checking .................................................................................................................. 23
7.1.4 Naming and Saving Electronic Files ................................................................................... 24
7.1.5 Preparing a Manuscript for a Multi-author Document ...................................................... 25
7.2 Manuscript Editing .................................................................................................................... 25
7.3 Proofreading ............................................................................................................................. 27
7.3.1 Stages of Proof .................................................................................................................. 27
7.3.2 How to Proofread and What to Look For .......................................................................... 27
8 Grammar and Usage ......................................................................................................................... 29
8.1 Nouns ........................................................................................................................................ 29
8.2 Pronouns ................................................................................................................................... 29
8.3 Adjectives .................................................................................................................................. 30
8.4 Verbs ......................................................................................................................................... 30
8.5 Adverbs ..................................................................................................................................... 30
8.6 Prepositions .............................................................................................................................. 30
8.7 Conjunctions ............................................................................................................................. 31
8.8 Interjections .............................................................................................................................. 31
8.9 Parallel Structure ...................................................................................................................... 32
9 Chicago Manual of Style .................................................................................................................... 33
April 2016
1
1 Introduction
All deliverable materials are considered formal representations of First Data in response to a client request for services and must be written in a formal style or technical style for technical documents. Refer to the Chicago Manual of style for all formal and technical writing styles, since all works written within EFTPS must comply with the Chicago Manual of Style for consistency.
Use the Quick Start Guide for some tips and tricks that may help you brush up on writing professionally. However, this guide is very brief and provides only a small dose of information.
April 2016
2
2 Quick Start Guide
All First Data deliverables are representative of our professionalism and how we represent our clients. Your writing style is distinguished by a professional writing style as described in the Chicago Manual of Style. Keep it professional and use:
Active voice/present tense
Easy to understand terms
Stick to the facts
Be succinct
Use structure;
Numbered headings
Numbered sub-headings
Caption tables and figures
Introduction, body, conclusion
Automatic numbering for procedures and processes
Bullet lists
Say exactly what you mean
2.1 Professional Voice Do’s and Don’ts
Table 2-1 Professional Voice Do’s and Don’ts
DO DON’T
Only one example and denote it with, “for example.”
“I.e.” when giving an example because it means, “in other words.”
Easy to understand terms Slang or complicated terms
Short informative sentences Run-on sentences
Qualifying adjectives in small amounts Qualifying adjectives (‘a nervous person' or `a musical speaking voice')
To show possession, use, “its.” Contractions “it’s.”
April 2016
3
DO DON’T
Define acronyms ‘first-time use’ and then acronym only. Include an Acronym List and corresponding Glossary denoting the terms used in the document.
The same acronym for different terms.
Always write out Electronic Federal Tax Payment System (EFTPS) the first time it is used in the document.
EFTPS (acronym) in the document title.
Electronic Federal Tax Payment System (spelled out) in the document title.
State when an item is a requirement or an expectation.
Be vague
Caption and cross-reference tables and figures. The table of contents will have a general list, a list of figures, and a list of tables.
Standard font without field codes.
Active voice and present tense.
For example, “The [PROJECT] has established performance standards or Service Level Agreements (SLAs) for service areas such as performance, service desk, system availability, and system planning.”
Am, is, are
“to be”
If the noun following the indefinite article begins with a vowel or has a silent consonant, use “an.”
An account manager An EFTPS subsystem An hour (the “h” is silent
“… a EFTPS” “… an Direct Pay”
Pronoun use is acceptable such as, “our, we, you, your.”
Replace, “I, me, and my” with, “our and we.” New business and technical writing styles have
evolved to sound more personal, warm, and friendly.
Use stoic and clinical tones.
April 2016
4
2.2 Punctuation Do’s and Don’ts
Table 2-2 Punctuation Do’s and Don’ts
Do Don’t
One space after punctuation Two spaces between words and sentences. Spaces as a way to indent.
Punctuation is placed inside quotation marks Place punctuation outside of quotation marks.
“Smart quotes,” the correct quotation marks and apostrophes, are curly or sloped.
"Dumb quotes," or straight quotes, are a vestigial constraint from typewriters when using one key for two different marks helped save space on a keyboard.
Bulleted lists for two or more items Only one bullet, or one number.
Punctuation in bulleted or numbered lists for complete sentences only.
Punctuation for fragments in a list.
A comma before the conjunction in a series (hardware, software, and network)
Use to indicate a small break in the sentence.
Overuse commas in a sentence.
Hyphens, en dash, em dash
Hyphens join conjunctions (two words) Em dash takes the place of commas,
parenthesis, and colons
En dash
Hyperlinks in small numbers. Maintaining them is very difficult.
Overuse hyperlinks because they are difficult to keep current.
April 2016
5
2.3 Common EFTPS Client, Project, and Products
Refer to the complete, and continuously updated, Glossary and corresponding Acronym List located in SharePoint.
Table 2-3 EFTPS Client, Project, and Products
Description Name
Clients Fiscal Service (FS) Internal Revenue Service (IRS) Bank of America Merrill Lynch (BAML)
Our Project Electronic Federal Tax Payment System (EFTPS)
The Products EFTPS Online Direct Pay
April 2016
6
3 EFTPS Style Sheet
3.1 Overview
EFTPS has a formatted and stylized template for MS Word, with the filename, EFTPS_Document-Template. A user can open the template, save the file under a new name using, “Save As,” and paste content from another document, or write content directly into the template. Please use this template for all EFTPS documents.
The Technical Writer is available for questions and assisting with pasting content, so the template formatting remains intact.
3.2 Styles
The styles used for Word documents are described in this section. Appendix A includes a Word template.
Documentation is always stylized as flush left, right ragged. Do not use the justified margins options for creating documents because inconsistent spacing makes it more difficult to read the content and the document looks very unprofessional.
3.2.1 Style Conventions
Table 3-1 Style Conventions
Usage Description Example
Page Header Calibri Body12 pt. bold dark green (R)0, (G)108, (B)49. All characters are uppercase.
SENSITIVE BUT UNCLASSIFIED
Heading Level 1 Cambria Headings 14 pt. bold dark blue (R)54, (G)95, (B)145. Letter case.
1.0 Overview
Heading Level 2 Cambria Headings 14 pt. bold medium blue (R)79, (G)129, (B)189. Letter case.
2.1 Entrance Criteria
April 2016
7
Usage Description Example
Heading Level 3 Cambria Headings 11 pt. bold medium blue. Letter case.
3.1.1 Meetings
Body Text Calibri Body 12 pt. regular font in black. Use Letter case. Flush left, ragged right.
The purpose of this document is …
Emphasis Calibri Body 12 pt. bold font in black. Use Letter case.
Name of GUI field or icon.
Emphasizes a section within the document Appendix CMP-001.
Emphasizes first-use cross-references
“Quotations” Calibri Body 12 pt. smart quotes regular font in black. Use Letter case.
“Application Name”
Publication Title Calibri Body 12 pt. italic font in black. Use Letter case.
IT Security Policy Manual and Standard 205: Configuration Management
List Bullets
Calibri 11 pt. regular font in black. Letter case. Bullets are 8pt (R)127, (G)127, (B)127.
Mainframe Compiled Code
Table Header Calibri 12 pt. bold font in orange (R)227, (G)108, (B)10. Letter case.
Description
Table Body Text
Calibri 11 pt. regular font in blue (R)54, (G)95, (B)145. Letter case.
Software Development Life Cycle
April 2016
8
Usage Description Example
Table List Bullets
Calibri 11 pt. regular font in blue (R)54, (G)95, (B)145. Letter case. Bullets are 8pt (R)127, (G)127, (B)127.
Mainframe
Compiled Code
Table Caption
Calibri 10 pt. bold font in black. Letter case. Centered on page and positioned above the table.
Table 1.0 SDLC Quality Assurance
Figure Caption
Calibri 10 pt. bold font in black. Letter case. Centered on page and positioned below the figure.
Figure 2.1 SDLC Process Flow
Subtle Emphasis Calibri 12 pt. italic font in gray (R)128, (G)128, (B)128. Letter case.
Configuration Hardware
Subtitle Cambria Heading 12 pt. italic font in bright blue (R)79, (G)129, (B)189. Letter case.
Hardware and Software
Website Address
Courier New 10 pt. regular font in black. Camel case. Aligned left.
http://intranet.Fiscal
Service.treas.gov
i .e. or e.g.
i.e. is the abbreviation of the Latin phrase ‘id est,’ meaning ‘that is.’
e.g. is the abbreviation of the Latin phrase ‘exempli gratia,’ meaning ‘for example.’
Use i.e. when you want to give further explanation for something.
Use e.g. when you want to give a few examples but not a complete list.
April 2016
9
Usage Description Example
Versus, vs, or vs.
Contexts, “vs.” (American English) or “vs” (British English) can be used as an abbreviation. This usage is more casual than writing out “versus.”
vs.
Time
Numerals are used (with zeros for even hours) when exact times are emphasized. Chicago recommends lowercase a.m. and p.m. with periods.
8:00 a.m. 5:00 p.m.
3.2.2 Headings
Table 3-1 displays the style conventions used for headings. The headings are managed in list levels that
look like:
1 Heading One
1.1 Heading Two
1.1.1 Heading Three
1.1.1.1 Heading Four
1.1.1.1.1 Heading Five
3.2.2.1 Additional Information about Headings
Heading One begins on a new page
Heading levels stop at Level 5
Use these features to avoid widows and orphans:
“Keep lines together”
“Keep with next”
Appendix Headings
Use alpha characters, A, B, C, and so on
Use Heading One style without the a numerical value
April 2016
10
4 PowerPoint Deck Style Conventions
The EFTPS PowerPoint template uses the filename, EFTPS_PowerPoint-Template. Appendix B displays an EFTPS PowerPoint deck.
Table 4-1 EFTPS PowerPoint Style Conventions
Usage Description Example
Slide Header The EFTPS logo resides in the upper left corner of every slide.
Slide Footer Left
The Bank of America Merrill Lynch logo is located in the lower left corner of every slide.
Slide Footer Right The First Data logo is located in the lower right corner of every slide.
Deck Title Calibri Heading 36 pt. black (the example shows 14 pt. for illustration purposes only).
1.0 Overview
Date on Deck Cover Calibri Heading 18 pt. black (the example shows 14 pt. for illustration purposes only).
April 2016
Slide Headings
Calibri Heading 22 pt. black (the example shows 14 pt. for illustration purposes only).
Executive Summary
April 2016
11
Usage Description Example
First Level
Calibri Body 24 pt. regular font in black. Use Letter case. Square bullet (the example shows 14 pt. for illustration purposes only). Flush left, ragged right.
First Level
Second Level
Calibri Body 20 pt. regular font in black. Use Letter case. Square bullet (the example shows 14 pt. for illustration purposes only). Flush left, ragged right.
Second Level
Third Level
Calibri Body 16 pt. regular font in black. Use Letter case. Square bullet (the example shows 14 pt. for illustration purposes only). Flush left, ragged right.
Third Level
Fourth Level
Calibri Body 16 pt. regular font in black. Use Letter case. Square bullet (the example shows 14 pt. for illustration purposes only). Flush left, ragged right.
Fourth Level
Fifth Level
Calibri Body 14 pt. regular font in black. Use Letter case. Square bullet. Flush left, ragged right.
Fifth Level
April 2016
12
Usage Description Example
Emphasis Calibri Body bold font in black. Use Letter case.
Name of GUI field or icon.
Emphasizes a section within the document Appendix CMP-001.
Emphasizes first-use cross-references
“Quotations” Calibri Body smart quotes regular font in black. Use Letter case.
“Application Name”
Publication Title Calibri Body italic font in black. Use Letter case.
IT Security Policy Manual and Standard 205: Configuration Management
Table Header Calibri 12 pt. bold font in orange (R)227, (G)108, (B)10. Letter case.
Description
Table Body Text
Calibri 11 pt. regular font in blue (R)54, (G)95, (B)145. Letter case.
Software Development Life Cycle
Table List Bullets
Calibri 11 pt. regular font in blue (R)54, (G)95, (B)145. Letter case. Bullets are 8pt (R)127, (G)127, (B)127.
Mainframe
Compiled Code
Table Caption
Calibri 10 pt. bold font in black. Letter case. Centered on page and positioned above the table.
Table 1.0 SDLC Quality Assurance
April 2016
13
Usage Description Example
Figure Caption
Calibri 10 pt. bold font in black. Letter case. Centered on page and positioned below the figure.
Figure 2.1 SDLC Process Flow
Subtle Emphasis Calibri 12 pt. italic font in gray (R)128, (G)128, (B)128. Letter case.
Configuration Hardware
Subtitle Cambria Heading 12 pt. italic font in bright blue (R)79, (G)129, (B)189. Letter case.
Hardware and Software
Website Address
Courier New 10 pt. regular font in black. Camel case. Aligned left.
http://intranet.Fiscal
Service.treas.gov
April 2016
14
5 Document Parts
5.1 Introduction
Noting differences between print and electronic versions. Although a printed article should include all elements that are essential to understanding, interpreting, and documenting the text, some white papers publish special materials electronically that are not available in the print version.
These features may include very large tables, supplemental reading lists, audio visual components, large data sets that can be exported to third-party software for analysis, or color versions of figures published in black and white in the printed journal; some of this material may constitute the basis of an online-only appendix.
5.2 Sensitive but Unclassified
The classification used in certain document headers and footers are:
Sensitive but Unclassified
Documents that contain EFTPS and Direct Pay process-related information, hardware and proprietary
software data, and other information that potentially can compromise or disrupt the integrity of the
project are classified using the Sensitive but Unclassified classification in the document headers and
footers stamped on every page.
5.3 Page Numbers
The cover does not include headers, footers, and page numbers. Page numbering begins on the page that comes after the cover page, and uses the lower case roman numerals in the lower right corner.
Page 1 begins on the first page of the white paper (Introduction, Overview, Executive Summary), and is denoted with the numerical “1” in the lower right corner. Pages in the appendices are not numbered.
5.4 Covers and Home Pages
Covers for printed white papers. EFTPS has document templates that include a cover.
Home pages for electronic white papers. At this writing, EFTPS does not have an internal online help, wiki, or other website.
April 2016
15
Maintaining the context of electronic articles. All documents are stored on SharePoint. At the time of this writing, there is no rules for file naming conventions, document control, or versioning.
5.5 Front Matter
Refer to the “Page Numbers” section for numbering front matter. All front matter includes pertinent material for consistency in this particular order:
Cover Page
Revision Log
Approvals (where applicable for compliance documents)
Table of Contents
List of Figures
List of Tables
Style Conventions
Blank Page (where applicable for documents usually sourced from the client)
Table of Contents. The Table of Contents (TOC) is generated using the Auto References Tool in Word, and should not go below 4 levels. The TOC will include a List of Figures and List of Tables. Update the TOC at the very end, after all changes have been made, and before uploading to SharePoint.
Information for Contributors. Include the authors’ names on the cover of the document.
5.6 Hyperlinks
The document can contain hyperlinks to external documents or connect to sections contained within the document. Use hyperlinks in small numbers because they are difficult to maintain current, and when external documents/files are moved, the link breaks.
5.7 Tables and Illustrations
Tables. Use styles for table text, table headers, and table bullets in the EFTPS template.
Illustrations. Follow the style used in the EFTPS template called, “Image.”
April 2016
16
5.8 Back Matter
5.8.1 Appendixes
An appendix may include explanations and elaborations that are not essential parts of the text but are helpful to a reader seeking further clarification, texts of documents, long lists, survey questionnaires, or charts and tables. The appendix should not be a repository for odds and ends that the author could not work into the text. Relevant information that is too unwieldly or expensive to produce in print may be suitable for presentation on a website.
Appendixes usually follow the last chapter or section, though an appendix may be included at the end of a section if it is essential to the understanding content in the section. If multi-author documents from which offprints of individual sections will be required, an appendix must follow the section it pertains to. When two or more appendixes are required, they should be designated by either numbers or letters and each should be given a title as well. Appendixes may be set either in the same type size as the text proper or in smaller type.
5.8.2 Chronology
A chronological list of events may be useful in certain works. It may appear in the back matter under its own heading, but if it is essential to readers, it is better placed in the front matter, immediately before the text.
5.8.3 Endnotes
Endnotes, simply headed Notes, follow any appendix material and precede the bibliography or reference list (if there is one). The notes to each chapter are introduced by a subhead indicating the chapter number and sometimes the section title. The running heads to the ends to the endnotes should identify the text pages the notes apply to. Endnotes are normally set smaller than the text but larger than footnotes.
5.8.4 Glossary
Each entry in a glossary or list of abbreviations should begin on a new line, capitalized only if the term is capitalized in the text. Separate each term from the definition that follows with a period, colon, or an em dash. In a glossary, begin the definition with a capital letter, as if it were a new sentence; in a list of abbreviations, the expanded term should be capitalized or lowercased as it would be in text. Glossary entries need closing punctuation unless all definitions consist of incomplete sentences. Any term or abbreviation that is consistently italicized in the text (not just on first use) should also be italicized in the glossary or list of abbreviations. (Abbreviations of consistently italicized terms should generally themselves be italicized). Entries should be double-spaced and may be formatted in flush-and-hang style or with ordinary first-line paragraph indents. Avoid multiple columns.
April 2016
17
5.8.5 Bibliography or Reference List
Bibliographies and reference lists are normally set smaller than the text and in flush-and-hang style. For
a discussion of the various kinds of bibliographies, see Bibliographies and Endnotes in Section 7.
5.9 Version Control and Material not Available in Print
5.9.1 Corrections to Documents
Chicago Manual of Style considers the electronic version of an article to be the version of record; the print version, which should contain all elements that are essential to the document, may nevertheless include only a subset of the material available electronically.
Whenever the electronic version is considered the version of record, it is extremely important not to make undocumented changes to the file after the electronic publication date. Note that the release of electronic documents before they are published in print means that errors may turn up well before the print issue has been assembled.
5.9.2 Drafts and Near Final Drafts
Manuscripts are sometimes released before publication: authors themselves may circulate drafts within their peer group. They may post drafts according to internal policies. Preprints are not to be confused with final edited documents.
5.10 Design and Style
A document’s design features—physical, visual, and editorial—are created by the Technical Writer who designs a cover and templates that convey the overall look and feel of the product being represented. At this time, the specifications for all document features are added, and because the writer designs not for specific text but for categories of text—document title, author’s name, text, heads, subheads, body text—the design should be simple and flexible as well as visually pleasing and easy to read. It is up to the writer/editor to fir the items and document content into the overall design.
April 2016
18
6 Web-based Publications
6.1 Functional Features
As even a casual user of the Internet knows, web-based publications offer much more than content. Any discussion of the parts of a web-based publication must also consider the functional features it will have—search engines, note-taking capability, user-controlled display options, and so forth.
The process of determining, designing, and implementing such features, while driven largely by technical expertise, must also be guided by editorial sensibilities. This type of work represents a significant departure from traditional editorial duties, but it is nonetheless essential that functional features be developed with a clear understanding of the content and how the user will interact with that content.
Editors involved in any work being developed as a web-based publication may therefore reasonably be asked to play a role in the development of the publication’s functional features.
6.2 Navigation— the Primary Way to Organize Content for Web-based Publications
A web-based reference work must take into account the fact that readers will typically consult smaller pieces of content and will expect to be able to click through many parts of a work in a very short period of time.
Books and journals designed for the web also need to take this reality into account. Nonetheless, not every publication needs to be modeled on the perfect online-dictionary—in which any term within a definition is hyperlinked to the entry for that term and so on, providing endless pathways through a significant subset of a single written language. Some readers will want the option merely to browse. At the very least, cross-references by being hyperlinked, will become more useful in any online publication, and most web-publications will need to augment or even replace standard table of contents with a search engine—one that may need to accommodate complex queries.
Furthermore, any web-based work that allows full-text searching will benefit from context-sensitive keyword indexing. Readers will also want to know where they’ve been and perhaps where other readers have been. They may want to take notes that they can return to later—through a search or other means. They may want to send comments to the author or publisher, and they may want to read and comment on the comments of others. Finally, readers of web publications may expect links to related resources. All these items will need to be made accessible through a clear and consistent navigational hierarchy.
April 2016
19
6.3 Hyperlinks
In a web-based publication, cross references become one of the primary ways in which a reader can expect to move quickly from one part of a work to another. There is no cost to following a hyperlink, provided there is a means of stepping or linking back and forth between the hyperlink and the item it points to. But if there are too many links, or if they do not tend to lead to strongly related content—or, worse, if they fail—a publication risks irritating its readers. Beyond cross-references and hyperlinked tables of contents and indexes or other navigational items, a link can of course be made to point to almost anything. Words might be linked to their definitions—either in a glossary or through a third-party dictionary.
Authors’ names might contain mail-to links or lead to their networking pages or to lists of their other works. URLs or other identifiers can be embedded in any piece of content. All of these must be maintained and updated, however, often at significant cost. internal cross-references are the most stable type of hyperlink because they need only be tested against and updated along with the work itself—a process that can be at least partly automated. Most other types of text-based links need to be weighed for their utility and persistence. On the other hand, some links can be generated programmatically—for example, links to related titles or related subjects generated by matching author, title, or subject metadata against an evolving database each time a user calls up a specific piece of content.
6.4 Front Matter
Readers of web-based publications will want to be able to navigate primarily to the core content of the publication (and the content that it generates) rather than to ancillary elements such as prefaces, copyright information, or information about the publication or its authors.
Online, these elements can be demoted from their usual position in the front of a printed-and-bound book and made accessible through a link at the edge of the screen or the base of a document, from which they can be consulted, if need be. Copyright information, however, should usually be included with each subdocument, and help and related documentation should also be available from any part of a publication.
Much of the usual taxonomy for printed works—from copyright page to table of contents to preface, forward, and introduction—will benefit from a different set of categories (e.g., “about us” links, site maps, site menus and other tools, search engines, and the other elements of interest. The table of contents, however, especially in works that can be read in larger chunks—such as an online journal or this manual—may be a significant driver in the top-level navigation of a web-based publication.
April 2016
20
6.5 Folios, Running Heads, and Other “Print” Elements
One of the primary advantages of a traditional printed-and-bound book or journal is the presence of page numbers. Page numbers allow students and researchers to make precise citations to the works they consult, allowing readers in turn to retrace their steps. Web-based publications should keep this in mind when designing and organizing content. Dictionaries and encyclopedias have a de facto organizing principle: readers cite material sub verbo—or “under the word”—that is, by entry or entry title. But other types of types of publications broken into scrollable sections or articles do not have page numbers and are not referenced by page number.
On the other hand, running heads almost always have analogous presence in the basic navigational elements of a web-based publication. Readers require clear indications not only of “where” they are within the publication at any moment, but also where they have been and where they may be going next.
6.6 Indexes, Notes, and Other Back Matter
Any web-based project can benefit from keyword-enhanced searches, cross-references to related content, and other navigational cues. Web-based works that have a printed counterpart complete with index, on the other hand, should take advantage of the intellectual labor that went into choosing and arranging the index entries and marry it to the linking capabilities of an electronic work.
An index prepared with human input—whether it is embedded and shows up only in the results of keyword searches or is prepared in an electronic work, whether or not it has a printed counterpart. Note references are hyperlinked to the text in electronic works, solving the problem of footnotes versus endnotes that arises in printed works.
Other traditional back matter—such as appendixes and bibliographies—may benefit in web-based works from electronic enhancements or links out to other resources.
April 2016
21
7 Document Preparation, Editing, and Proofreading
7.1 Formatting
Table 3-1 shows the EFTPS style conventions used in Word documents. In this section, we discuss general formatting methods.
Line spacing. Single space.
Word spacing. Single character space, including after colon and semi-colon.
Justification and margins. To maintain a consistent appearance throughout a document, all text should be presented flush left (ragged right) – lines should not be justified to the right margin. Use one-inch margins unless otherwise noted in a template.
Spaces, tabs, and hard returns within paragraphs. A well-structured electronic document will never include more than one consecutive character space. A tab or hard return paragraph break should never appear within a paragraph. It is unnecessary to indent the first line of a paragraph. Do not use the space bar to indent or tab; instead use the tab or indent features.
Hyphenation. The only hyphens (-) that should be in the document are hyphens used for compound forms. Hyphenation is not necessary for long words at the end of a line.
Dashes. An em dash (—) indicates a break in a sentence like this—either use the em dash character or type two hyphens and leave no space on either side. The en dash (–) is the shorter dash and is used for certain types of compounds and number ranges. Consult the technical writer for more information.
Italics, underline, and boldface. Underlining conveys different things such as italics usage or denotes editorial changes
Special characters. Use the correct character you intend to use rather than a substitute. For example, if you want to use the prime symbol, be sure to use the symbol by inserting the symbol from the symbol list rather than using an apostrophe.
Chapter and other titles. Chapter and Section titles begin on a new page. Sub-sections do not require a new page. use upper- and lowercase letters rather than full capitals. The titles should be consistent so they match entries in the Table of Contents.
Page numbers and pagination. Page numbers are flush right in the footer. All front matter uses the roman numerals format (i, ii, iii …) and begin on the first page following the cover page. The cover page does not have a page number. At the beginning of Section or Chapter 1, page
April 2016
22
numbers begin with 1 and use the numerical format (1,2,3…). Back matter or the appendices use, “Appendix” in the footer followed by A,B, C in the page number field.
Subheads. Set subheads on a new line, flush left. Each subheading must be distinguished by type size and style, such as larger boldface for first-level subheads versus smaller italics for second-level subheads. Use upper- and lowercase letters rather than full capitals. Except for run-in heads, which are usually italicized and given initial capitals for the first word and proper names only (sentence style), subheads are almost never followed by a period.
Footnotes and endnotes. Use the automatic numbering and create notes tools offered in Word. Create foot- and endnotes automatically using the Footnotes feature shown in the References tab on you Word Ribbon. The tool links the numbering and automatically links to the footnote placed at the bottom of the page. Notes to tables should be numbered separately, and this is addressed in the Illustrations and Tables Section.
Glossaries and lists of abbreviations. Each entry in a glossary or list of abbreviations should begin on a new line, capitalized only if the term is capitalized in the text. Separate each term from the definition that follows with a period, colon, or an em dash. In a glossary, begin the definition with a capital letter, as if it were a new sentence; in a list of abbreviations, the expanded term should be capitalized or lowercased as it would be in text. Glossary entries need closing punctuation unless all definitions consist of incomplete sentences. Any term or abbreviation that is consistently italicized in the text (not just on first use) should also be italicized in the glossary or list of abbreviations. (Abbreviations of consistently italicized terms should generally themselves be italicized). Entries should be double-spaced and may be formatted in flush-and-hang style or with ordinary first-line paragraph indents. Avoid multiple columns.
Bibliographies and reference lists. Although a bibliography or reference list will often appear in flush-and-hang (or hanging-indentation) style in the published version, you may either use the hanging-indention function, or format each entry like a normal paragraph with a first line indent. Never use the Tab key to indent runover lines.
7.1.1 Illustrations and Tables
Separate files for illustrations , captions, and tables. For larger documents (more than 50 pages), it is preferred to use separate files for illustrations and tables. All illustrations and tables must be captioned. Illustrations include a caption at the bottom and include the section (chapter) number and illustration number. Tables are captioned at the top and include section number and table number. It is not necessary to cross-reference captions. However, it is beneficial and recommended to cross-reference illustrations and tables at least one time. Use the Cross-reference tool in Word to caption and automatically cross-reference illustrations and tables.
April 2016
23
Table notes and source notes. Source notes appear at the foot of the table before any other notes. They are preceded by the word, “Source,” followed by a colon. Other notes to the table as a whole follow any source note and may be preceded by the word, “Note,” followed by a colon. Specific notes follow any other notes and must carry their own numbering (preferably letters), keyed to parts of the table. They must never be numbered along with the notes to the text.
7.1.2 Bibliography and References
7.1.2.1 Notes (Footnotes and Endnotes)
Full citation in a note
1. Newton N. Minow and Craig L. LaMay, Inside the Presidential Debates: Their Improbable Past and Promising Future (Chicago: University of Chicago Press, 2008), 24–25.
Shortened citation in a note
8. Minow and LaMay, Presidential Debates, 138.
Entry in bibliography
Minow, Newton N., and Craig L. LaMay. Inside the Presidential Debates: Their Improbable Past and Promising Future. Chicago: University of Chicago Press, 2008.
Note citations are styled much like running text, with authors’ names in normal order abd the elements separated by commas or parentheses. In bibliographies, where entries are listed alphabetically, the name of the first author is inverted, and the main elements are separated by periods.
7.1.3 Cross-checking
Items to cross-check. Before submitting a document for release, an author must cross-check all of its
parts to avoid discrepancies. The following list includes major items to check:
All titles and subtitles (introduction, parts, chapters, etc.) against table of contents
Subheads against table of contents (if subheads are included there)
Illustrations against their captions, text references, and callouts
Illustration captions against list of illustrations
Tables against their text references and callouts
Table titles against list of tables
All cross-references
In an electronic work, all hyperlinks
April 2016
24
Notes against their text references
Notes against bibliography
Parenthetical text citations against reference list
Abbreviations against list of abbreviations
Abbreviations against first time use with definition
In a multi-author work, authors’ names in table of contents against chapter headings and list of contributors
Checking quotations. All quoted matter should be checked against the original source, for both content and citation.
Checking URLs. Any URLs must be verified they connect to the intended source.
Checking cross-references. Verify all cross-references including, chapter, section, appendix, and text in a sentence. Cross-references are best made to chapter/section numbers. (Keep in mind that references to whole chapters are often gratuitous and unhelpful; it’s best to avoid peppering a document with “see chapter 2 above” and “see chapter 4 below”.) References to page numbers are generally discouraged because the pagination often changes.
7.1.4 Naming and Saving Electronic Files
Creating separate files. For large documents, authors may prefer to get separate electronic files for each of the various elements—front matter through table of contents, preface chapters/sections, appendices, and so on (some of which will contain embedded notes). It is recognized, however, that some authors prefer to work in one electronic file. Nonetheless, appropriately named separate files—especially for complex works—can help get a sense of a book’s/manual’s parts. Illustrations should always be in separate files. Tables can be in separate files, but it isn’t necessary.
Naming files. For documents with more than a few parts, it may be helpful to choose file names that will line up in book order in an alphanumerically sorted directory. For example, “Chapter 01 EFTPS Billing,” “Chapter 02 Direct Pay,” “Chapter 03 Bank of America Merrill Lynch.” This type of naming convention keeps the files in alphanumerical order, and indicates the number of each chapter—an additional organizational cue. File names should correspond, more or less, to the parts in the document listed in the table of contents. A complete list of all submitted files, including lists of illustrations, tables, or any electronic-only elements, should accompany the document. (For hard copy documents, the various divisions should be arranged in the order specified in the table of contents, which is not necessarily the order of the electronic directory.) Files for color illustrations may include the word color in their names, especially if black and white prints have also been submitted.
April 2016
25
Numbering pages. Each page of the document must be numbered. Documents submitted as multiple files need not be numbered consecutively from page 1 through to the end of the document. Page numbers are flush right in the footer. All front matter uses the roman numerals format (i, ii, iii …) and begin on the first page following the cover page. The cover page does not have a page number. At the beginning of Section or Chapter 1, page numbers begin with 1 and use the numerical format (1,2,3…). Back matter or the appendices use, “Appendix” in the footer followed by A,B, C in the page number field.
Embedded comments and revision marks. Authors should delete any comments embedded in their electronic document before submitting it as final. This includes any text formatted as “hidden” and any comments generated using the commenting feature. All tracked changes and revision marks.
Backing up the final manuscript. In addition to saving a separate electronic copy of each crucial stage of work on the document, authors are advised to save a backup copy of the final version.
7.1.5 Preparing a Manuscript for a Multi-author Document
Editor’s preparation responsibilities. The specific responsibilities of the editor and contributors must be determined before a multi-author document is submitted. After ensuring that the contributors furnish their papers in a uniform style agreed to by all parties, the editor is usually responsible for the following:
Getting manuscripts, including illustrations, from all contributors in a form acceptable to the editor well before the submittal date.
Getting written permission from copyright owners to reproduce material in copyrighted works written elsewhere, illustrations taken from another work, and so on.
Editing each section for sense and checking references and other documentation for uniformity of style
Providing a list of contributors
Verifying all queries and comments have been addressed
Providing a title page, table of contents, and any necessary prefatory material
Sending the document to the document author or authors for final review
Accepting all changes, deleting comments, checking for pagination, footers, headers, updating table of contents, and filing document according to author or authors’ instructions
7.2 Manuscript Editing
Manuscript editing as opposed to developmental editing. Copy editing requires attention to every word and mark of punctuation; a thorough knowledge of the style follows, and the ability to make quick, logical, and defensible decisions. It may include mechanical editing and substantive editing. It is distinctive from developmental editing, which more directly shapes the
April 2016
26
content of a work, the way a material should be presented, the need for more or less documentation and how it should be handled, and so on. Since editing of this kind may involve total rewriting or reorganization of a work, it should be done—if needed—before manuscript editing begins.
Mechanical editing. Mechanical editing involves the consistent application of a particular style to a written work—including text and documentation and any tables and illustrations. Mechanical editing also pays attention to grammar, syntax, and usage.
Substantive editing. Substantive editing deals with the organization and presentation of content; it involves rewriting to improve style or to eliminate ambiguity, reorganizing or tightening, recasting tables, and other remedial activities (this is not to be confused with developmental editing).
Estimating editing time. Estimates for how long the job of manuscript editing should take—a figure determined by the editor—usually depends on the length of the manuscript. This rough estimate may need to be adjusted to take into account any complexities in the text or documentation, the presence and characteristics of any tables and figures, and the degree of electronic formatting and markup that an editor will need to remove or impose. Also pertinent is information about the author’s availability to review the edited manuscript, amenability to being edited, propensity to revise, and so forth.
Stages of editing. Editors usually go through a manuscript three times—once to do the initial editing, easily the longest stage; a second time to review, refine, and sometimes correct the editing; and a third time after the author’s review. Editors working on electronic manuscripts may also be required to perform an initial clean, systematic cleanup. Careful editors begin the initial editing stage—sometimes in conjunction with the electronic cleanup—by looking through the entire document to assess the nature and scope of the work that will be required, to identify any matters that should be clarified with the author before editing begins, and to reduce the number of surprises that could cause delays if discovered later in the process. Some edit each element in a work (text, notes, tables, bibliography, etc.) separately to help attain consistency; other edit the apparatus, or a part of it, along with the text. Whatever the procedure, all elements must be compared to ensure that the notes match their text references and correspond in turn to the entries in the bibliography or reference list, the tables correspond to any discussion of them in the text, and so on.
Choosing a dictionary and other reference works. A good dictionary is essential. Chicago recommends Webster’s Third New International Dictionary and the latest edition of its chief abridgement, Merriam Webster’s Collegiate Dictionary.
Keeping a style sheet. To ensure consistency, for each manuscript the editor must keep an alphabetical list of words or terms to be capitalized, italicized, hyphenated, spelled, or
April 2016
27
otherwise treated in any way unique to the manuscript. Changes that are made simply for consistency with house style need not be noted on the style sheet.
Fact Checking. The author is finally responsible for the accuracy of the work.
7.3 Proofreading
What is proofreading? Proofreading is the process of reading a text and scrutinizing all its components to find errors and mark them for correction. Proofreading applies to the review of the manuscript after it has been converted into its final form.
Who should proofread? For the majority of documents, authors are considered the primary proofreaders, and it is they who bear the final responsibility for any errors.
7.3.1 Stages of Proof
Keeping a record of each proofreading stage. A record must be kept of when each stage of proof has been corrected and by whom. Use version control software to maintain accurate records of proofreading and editing stages.
First proofs. The author and sometimes designated proofreader read the first proofreading copy.
Revised proofs. After corrections to the first proofs have been made, the revisions must be checked to ensure all corrections have been made accurately. Using “tracked changes” is useful for completing this task.
7.3.2 How to Proofread and What to Look For
Proofreading against copy. In proofreading parlance, copy refers to the edited manuscript. Proofs should be checked against the version of the manuscript that contains the author’s final changes and responses to the queries. A proofreader must read word for word against the edited manuscript, noting all punctuation, paragraphing, , capitalization, italics, and so forth. Any math or data contained in tables must be proofread for accuracy, and is done by the author who is responsible for the content. The manuscript must be kept intact, unaltered, and a proofreader must only mark the proofs (a new version).
Proofreading for spelling errors. The proofreader should remain alert for the kind of errors that are typically missed by “spell check”—from common typos such as it’s where its is meant or out where our is meant, to more subtle errors like lead for led or breath for breathe. Note that a change to the spelling of a particular term should never be indicated globally; instead, each change must be marked throughout the manuscript.
April 2016
28
Checking word breaks. End-of-line hyphenation should be checked, especially in proper names and foreign terms.
Checking typeface and font. Each element in proofs—for example, chapter numbers and titles, subheads, text, extracts, figure captions—should be checked to ensure that it is presented in a consistent typeface and style in accordance with the style guide.
Checking and proofreading page numbers and running heads. Page numbers and running heads must be checked to ensure they are present where they are supposed to be and absent where they are not, and that the correct page number appears following a blank page. Running heads must be both proofread and checked for placement.
Checking and proofreading illustrations and tables. The proofreader must verify that all illustrations appear in the right location in the text, in the right size, right side up, not “flopped” or distorted, and with their own captions. Captions should be read as carefully as the text. Tables must be proofread both for content and for alignment.
Checking overall appearance. For printed works, each page should be checked for length, vertical spacing, position of running heads and page numbers, and so forth. Conformity to the design specifications must be verified. Avoid widows and orphans—a widow is a paragraph-ending line that falls at the beginning of the following page or column, thus separated from the rest of the text, whereas, an orphan is a paragraph-opening line that appears by itself at the bottom of a page or column, thus separated from the rest of the text.
Proofreading for sense. The proofreader must query, or correct, illogical, garbled, repeated, or missing text. Any rewriting, however, must be limited to the correction of fact or of gross syntactical error, since all source checking and substantive and stylistic changes should have been done at the editing stage. Changes that would alter page makeup across more than a couple of pages should be avoided, since this affects repagination which is very time consuming to alter.
April 2016
29
8 Grammar and Usage
Grammar consists of the rules governing how words are put together into sentences. These rules govern most constructions in a given language.
8.1 Nouns
Nouns generally. A noun is a word that names something, whether abstract (intangible) or concrete (tangible). It may be a common noun (the name of a generic class or type of person, place, thing, process, activity, or condition) or a proper noun (the formal name of a specific person, place, or thing).
Common nouns. A common noun is the generic name of one item in a class or group (a chemical) (a river) (a pineapple). It is not capitalized unless it begins a sentence or appears in a title. Common nouns are often broken down into three subcategories; concrete nouns, abstract nouns, and collective nouns. A concrete noun denotes something solid or real, something perceptible to the physical senses (a building) (the wind) (honey). An abstract noun denotes something that you can’t see, feel, taste, hear, or smell (joy) (expectation) (neurosis). A collective noun—which can be viewed as a concrete noun, but is often separately categorized—refers to a group or collection of people or things (a crowd of people) (a flock of birds) (a committee).
Proper nouns. A proper noun is the specific name of a person, place, or thing (John Doe) (Moscow) (the Hope Diamond), or the title of a work (Citizen Kane). A proper noun is always capitalized, regardless of how it is used. A common noun may become a proper noun (Old Hickory) (the Big Easy), and sometimes a proper noun may be used figuratively and informally as if it were a common noun (like Moriarty, he is a Napoleon of crime) (Napoleon here connoting an ingenious mastermind who is ambitious beyond limits).
8.2 Pronouns
Pronouns defined. A pronoun is a word used as a substitute for a noun or, sometimes, another, pronoun. It is used one of two ways: A pronoun may substitute for an expressed noun or pronoun, especially to avoid needless repetition. For example, most of the nouns in this sentence can be replaced with pronouns: The father told the father’s daughter that the father wanted the father’s daughter to do some chores can be replaced with pronouns: The father told his daughter that he wanted her to do some chores.
April 2016
30
Six Classes of Pronouns:
personal—I, you, he, she, it, we, they
demonstrative—that, this
interrogative—what, which, who
relative—that, what, which, who
indefinite—another, any, each, either, none
adjective—any, each, that, this, what, which
Many pronouns, except personal pronouns, may function as more than one type—for instance, that may be a demonstrative, relative, or adjective pronoun—depending on its use in a particular sentence.
8.3 Adjectives
Adjectives defined. An adjective is a word that modifies a noun or pronoun; it is often called a “describing word.” An adjective tells you what sort, how many, how large or small, whose, and so on. An adjective may add a new idea to a noun or pronoun by describing it more definitively or fully (red wagon) (human error). Or it may be limiting (three pigs) (this time).
8.4 Verbs
Verbs defined. A verb denotes the performance or occurrence of an action or the existence of a condition or a state of being, such as an emotion. Action verbs include walk, shout, taste, and fly. Nonaction verbs include imagine, exist,, and dread. The verb is the most essential part of speech—the only one that can express a thought by itself.
8.5 Adverbs
Adverbs defined. An adverb is a word that qualifies, limits, describes, or modifies a verb, an adjective, or another adverb. (she studied constantly—where constantly qualifies the verb studied).
8.6 Prepositions
Prepositions defined. A preposition is a word or phrase that links an object and an antecedent to show the relationship between them. A preposition’s object is usually a noun, or else a pronoun, in the objective case (between me and them), but an adjective, adverb, verb, or
April 2016
31
phrase may follow instead. For example, the preposition can end a clause, especially a relative clause, or sentence (this isn’t the pen that Steve writes with).
Simple and compound prepositions. Many prepositions are relatively straightforward. A simple preposition consists of a single monosyllabic word—for example, as, at, by, down, for, from, in, like, of, off, on, plus, since, through, to, toward, up, and with. A compound preposition has two or more syllables; it may be made up of two or more words (into) (outside) (upon). Some examples are about, above, across, after, against, alongside, around, before, below, beneath, between, despite, except, inside, onto, opposite, throughout, underneath, until, and without.
Participial prepositions. A participial preposition is a participial form that functions as a preposition (or sometimes as a subordinating conjunction). Examples include assuming, barring, concerning, considering, during, notwithstanding, owing to, provided, regarding, respecting, and speaking. Unlike other participles, these words do not create danglers when they have no subject (considering the road conditions, the trip went quickly) (regarding Watergate, he had nothing to say).
8.7 Conjunctions
Conjunctions defined. A conjunction connects sentences, clauses, or words within a clause (My daughter graduated from college in December. And my son will graduate from high school in May.)—and connects two sentences); (I said hello, but no one answered—but connects two clauses); (we’re making progress slowly but surely—but joins two adverbs within an adverbial clause). Conjunctions connect pronouns in the same case (he and she are colleagues) (the teacher encouraged her and me).
8.8 Interjections
Interjections defined. An interjection or exclamation is a word, phrase, or clause that denotes strong feeling (Never again!) (You don’t say!). An interjection has little or no grammatical function in a sentence; it is used absolutely (Really, I can’t understand why you put up with the situation.) (Oh no, how am I going to fix the damage?) (Hey, it’s my turn next!). It is frequently allowed to stand as a sentence by itself: (Oh! I’ve lost my wallet!) (Ouch! I think my ankle is sprained!) (Get out!) (Whoa!). Introductory words like well and why may also act as interjections when they are meaningless utterances (Well, I tried my best.) (Why, I would never do that!). The punctuation offsetting the interjections distinguishes them. Compare the different meanings of Well, I didn’t know him with I didn’t him well, and Why, here you are! with I have no idea why you are here and Why? I have no idea.
April 2016
32
8.9 Parallel Structure
Parallel structure generally. Parallel constructions—series of like sentence elements—are common in good writing. Compound structures may link words (win, lose, or draw), phrases (government of the people, by the people, for the people), dependent clauses (that all men are created equal; that they are endowed by their creator with certain inalienable rights; that among these are life, liberty, and the pursuit of happiness), or sentences (I came; I saw; I conquered). Every element of a parallel series must be a functional match of the others (word, phrase, clause, sentence) and serve the same grammatical function the sentence (e.g., noun, verb, adjective, adverb). When linked items are not like items, the syntax of the sentence breaks down:
Wrong: She did volunteer work in the community kitchen, the homeless shelter, and taught free ESL classes offered by her church.
Right: She did volunteer work in the community kitchen and the homeless shelter, and taught free ESL classes offered by her church.
April 2016
33
9 Chicago Manual of Style
The Chicago Manual of Style is the book we reference when working with words. Use the latest edition because changes within writing do occur, especially for web-based documents. The content for this guide was partially obtained from the manual’s 16th edition (2010).
