Volume TCN 707: EDITING & STYLE Aaron Courtice 12/7/2010 Prof. Scott Russell. Technical Communication Style Guide

Transcription

1 Volume 1 TCN 707: EDITING & STYLE 2010 Aaron Courtice 12/7/2010 Prof. Scott Russell Technical Communication Style Guide

2 TCN 707: EDITING & STYLE 2010 Technical Communication Style Guide Copyright 2010 by Aaron Courtice All Rights Reserved Printed in Canada

3 TABLE OF CONTENTS Table of Contents The Basis of Our Style... 1 Source Texts... 1 General Guidelines... 2 Task Oriented... 2 Accurate... 2 Complete... 2 Clear... 2 Defined... 3 Correct... 3 Organized... 3 Retrievable... 3 Visually Effective... 3 Spelling... 4 Conventions of Canadian Spelling... 4 Capitalization... 5 Common Instances of Capitalization... 5 Rules for Contextual Capitalization... 6 Abbreviation... 7 General Rules for the Use of Abbreviation... 7 Periods and Spaces in Abbreviations... 7 Capitalization in Abbreviations... 8 Numbers... 9 Representation of Numbers as Words and Numerals... 9 Measurement...10 Standard Metric Measurements Notes on Measurement Style Statistics...11 Guidelines for Working with Statistics Statistic-related Terminology Punctuation...13 Punctuation Conventions i

4 TABLE OF CONTENTS Notes on Punctuation Mark Usage Illustration...17 Guidelines for Illustration The Interaction of Text and Illustrations Tables...19 Guidelines for Table Style Example Table with Formatting Graphs...20 Guidelines for Graph Style Example Graph with Formatting Citation and References...21 Exemplary Citation Index...22 ii

5 CHAPTER ONE THE BASIS OF OUR STYLE Chapter 1 The Basis of Our Style Our official style is based on several industry standard texts. These texts are listed below and hyperlinked to the official source where possible. For further information and explanation, please consult these source texts. Source Texts Canadian Oxford Dictionary Canadian Press Stylebook Canadian Press Caps and Spelling Chicago Manual of Style Microsoft Manual of Style for Technical Publications Apple Publications Style Guide Sun Technical Publications: A Style Guide for the Computer Industry 1

6 CHAPTER TWO GENERAL GUIDELINES Chapter 2 General Guidelines Creating technical documentation demands precision in all aspects. Try to design your documents according to the following precepts: Task Oriented Information is appropriate for the audience. Information is presented from the user s point of view. A practical reason for the information is evident. The focus is on real tasks. The headings reveal the tasks. The tasks are divided into discrete subtasks. Step-by-step instructions are clear. Accurate Information has been verified. Information reflects the current subject or product. Information is consistent. References to related information are correct. Complete All topics that support user tasks are covered and no others. Each topic has the details users need and no more. Patterns of information ensure proper coverage. Clear The focus is on the meaning. The language is unambiguous. The elements flow from one to another. Information is presented in a consistent way. 2

7 CHAPTER TWO GENERAL GUIDELINES Technical terms are necessary and appropriate. Defined Each term that is new to the user is defined. Examples are appropriate for audience and subject. Code examples are easy to adapt. Scenarios illustrate tasks and provide product overviews. The context for examples and scenarios is described. Unfamiliar information is related to familiar information. General language is used appropriately. Correct Grammar, spelling and punctuation are correct and consistent. Tone and mood are appropriate. Style is active. Templates and boilerplate text are used appropriately. Style guidelines are followed. Organized Information is organized into discrete topics by type. Organization of the tasks is by order of use. Organization of the topics enables quick retrieval. Contextual information is separated from other types. Main points are emphasized; secondary points, subordinated. Users can see how the pieces fit together. Retrievable Navigation and search are easy. The index is complete and consistent. The table of contents has an appropriate level of detail. Links are appropriate and helpful. Linked information is easy to find in the target topic. Visually Effective Graphics are meaningful, appropriate, and complement text. Visual elements are used for emphasis. Visual elements are logical, consistent and balanced in use. Visual cues help users find what they need. Textual elements are legible. Colour and shading are discreet and significant. 3

8 CHAPTER THREE SPELLING Chapter 3 Spelling Our guidelines for spelling are predicated on the Canadian Oxford Dictionary and the Canadian Press Caps and Spelling guide. Canadian spelling is an amalgam of British and American spelling. As such, it can be confusing at times. Fortunately, British and American spellings are becoming more uniform toward the American standard. If in doubt concerning a matter of spelling, consult the source texts. Conventions of Canadian Spelling Table 1 illustrates several common conventions of Canadian spelling. Exemplary spelling of words is given alongside the convention titles. Convention Examples -c- and s- defence licence (n.) license (v.) diphthongs anemia hemorrhage orthopedic double consonant combatting libellous pedalled e + suffix acknowledgement judgment livable foreign plurals appendices bureaus referendums -l or ll appall enrolment instalment -our behaviour endeavour neighbour -re centre manoeuvre theatre -yze analyze catalyze paralyze Table 1: Spelling Conventions and Examples 4

9 CHAPTER FOUR CAPITALIZATION Chapter 4 Capitalization Our guidelines for capitalization are predicated on the Canadian Press: Caps and Spelling guide. Canadian Press follows a modified down style, meaning they prefer to use lower case letters whenever possible. If in doubt concerning a matter of capitalization, consult the source text. Common Instances of Capitalization Table 2 outlines some common instances of capitalization. Examples are given alongside categorical titles. The upward arrow ( ) indicates the need for capitalization. Category Companies Ethnicities Government departments Languages Nations Places and Addresses Proper names Religions Trade names Example Hudson s Bay Trading Company Métis Department of Justice Canada Mandarin Finland Toronto Islands Terry Fox Buddhism Bell Canada Table 2: Common Instances of Capitalization 5

10 CHAPTER FOUR CAPITALIZATION Rules for Contextual Capitalization Rules governing capitalization may vary by context. These rules are illustrated in Table 3. Examples are given alongside categorical titles. The upward arrow ( ) indicates the use of capitalization. The downward arrow ( ) indicates the use of lowercase. Category Capitalize Lowercase Formal Titles Occupational Titles and Job Descriptions Titles of Works Directly preceding a name. e.g. Professor Russell assigned homework Do not capitalize. Use title case and capitalize only: Standing alone or set off with commas. e.g. Scott Russell, the class professor, assigned homework Always use lowercase. e.g. author Farley Mowat once said Use title case and avoid the use of complete capitalization where possible. Table 3: Rules for Contextual Capitalization nouns pronouns adjectives adverbs verbs first and last words prepositions and conjunctions of four letters or more e.g. James and the Giant Peach 6

11 CHAPTER FIVE ABBREVIATION Chapter 5 Abbreviation Content weeded with abbreviations is hard to read and understand. Avoid using abbreviations whenever possible. General Rules for the Use of Abbreviation The following list outlines rules for the general use of abbreviations in our documentation. Give the full name on first reference and then the abbreviation in parenthesis. Use the abbreviation thereafter. In a long document, repeat the first reference in every chapter or appendix. For ease of reading or variety, use a general term instead of repeating the abbreviation frequently. Periods and Spaces in Abbreviations Table 4 outlines the conventions for using periods and spaces in abbreviations. Type of Abbreviation Use of Periods and Spaces Examples Currency Omit periods and spaces. C$1 million Lowercase and mixed-case Usually include periods. m.p.h. Mr. B.Comm. Metric Symbols Omit Period. cm ml Mixed-case starting and ending with a capital letter Omit periods. PhD U of T PoW Single letter Include period. 30 John St. E. Table 4: Periods and Spaces in Abbreviations 7

12 CHAPTER FIVE ABBREVIATION Capitalization in Abbreviations Table 5 illustrates conventions for capitalization in abbreviations. Type of Abbreviation Capitals or Lowercase Examples Acronym All capitals. AIDS CD-ROM Common Word All lowercase. scuba laser Initialism First letter capitalized, followed by lowercase. Dofasco Nabisco Suspension Table 5: Capitalization in Abbreviations First letter capitalized, followed by lowercase and period. Mr. Lt. 8

13 CHAPTER SIX NUMBERS Chapter 6 Numbers Technical writing regularly involves the use of numbers, as much of our subject matter concerns science and technology. For many writers, math and statistics are not areas in which we specialize. For this reason, it is important to verify the accuracy of your work when it involves numerical data. Representation of Numbers as Words and Numerals Conventions concerning the representation of numbers vary by context and number value. Table 6 outlines some of the Canadian Press rules for the representation of numbers. Number or Context Representation Example Casual use Word Thousands of people. Common fractions less than one Word The fraction of one-half. Currency Arabic Numeral The price of $100. Date, Time, Year Arabic Numeral The year Large numbers Word Over 245 billion burgers served. Measurement Arabic Numeral The gauge of 16 mm film. Score, Vote Arabic Numeral The score of 5-4. Sequences of people or animals Roman Numeral The film Godfather III. Whole numbers greater than 10 Arabic Numeral The number 11. Whole numbers less than 10 Word The number nine. Table 6: Representation of Numbers as Word and Numerals 9

14 CHAPTER SEVEN MEASUREMENT Chapter 7 Measurement The metric system has been the standard form of measurement in Canada since As the national standard, it is the system we use most frequently in our documentation. The system is based on units of 10, so each unit can be broken down, decimal by decimal, digit by digit. Standard Metric Measurements Table 7 lists the base units used in the metric measurement system. Abbreviations are given alongside the unit names and types. Unit Name Ampere (A) Candela (cd) Kelvin (K) Kilogram (kg) Metre (m) Mole (mol) Second (s) Unit Measured Current Luminosity Temperature Mass Length Substance Time Notes on Measurement Style When an imperial measurement is standard, give it and the metric equivalent in parentheses thereafter. Unless accuracy is required, tend to round equivalent measurements, rather than give an exact conversion. Table 7: Base Metric Units 10

15 CHAPTER EIGHT STATISTICS Chapter 8 Statistics Technical writing regularly involves the use of statistics, as much of our subject matter concerns science and technology. For many writers, math and statistics are not areas in which we specialize. For this reason, it is important to verify the accuracy of your work when it involves statistical data. Guidelines for Working with Statistics The following list provides some general guidelines for use of statistics in your documentation: Verify accuracy and beware of estimates. Date is extremely important. Make sure that it is clearly indicated and that the data remains valid. Beware of comparisons in data. Try to identify pertinent variables before drawing a comparison. Clearly identify the source study area. Ensure that all data is applicable to your subject matter. Statistic-related Terminology Table 8 offers definitions of common statistic-related terminology which you may find useful in your research and application of statistical data. Term Average Mean Median Mode Definition The quotient obtained by dividing the sum of values by the number of values. The number between the highest and lowest values, regardless of the intervening values. The middle value; if an even number of values exists, it is the value between the two middle values. The value in a set that occurs most frequently. 11

16 CHAPTER EIGHT STATISTICS Percent Change Per Capita Standard Deviation The quotient of the difference between the current value and the old value divided by the old value, multiplied by 100. The quotient obtained by dividing a statistic by the total population. The mean of the mean, meaning the distribution of values in a population tends toward the mean, with few values in the extremes. The standard deviation is the range of the mean. Table 8: Common Statistics Terminology 12

17 CHAPTER NINE PUNCTUATION Chapter 9 Punctuation Punctuation marks indicate the structure and organization of your text. These marks are vital to the audience's comprehension of your text. Clarity of meaning is a central tenant of technical communication, so be sure to make proper use of punctuation in your documents. Punctuation Conventions The following list outlines some general conventions of punctuation which you should employ in your technical writing: Add one space after end stop punctuation, rather than two. Don t indent or double space text. Let the space between paragraphs consistently indicate and separate paragraphs. Where appropriate, use an em dash ( ) rather than two hyphens. Likewise, use an en dash ( ) rather than a hyphen, where it is appropriate. 13

18 CHAPTER NINE PUNCTUATION Notes on Punctuation Mark Usage Table 9 outlines some conventions in the usage and application of certain punctuation marks. You should adhere to these conventions in your technical writing. Punctuation mark Apostrophe ( ) Colon (:) Comma (,) Usage Use an apostrophe to indicate possessive nouns, either with sor without. If there is joint possession, indicate possession on the last noun. Use an apostrophe to indicate contraction and other omissions of letters or numbers. Use an apostrophe to indicate the plural of letters, numbers, symbols, and words referred to as words. Don t use an apostrophe with possessive personal pronouns or with whose, to form the possessive of inanimate objects, or to form the plural of proper nouns. Use a colon to introduce a list following a grammatically complete sentence. Use a colon before a long quotation of one or more paragraphs. Use a colon before a formal quotation or question. Use a colon before a second independent clause that explains the first clause. Use a colon after the salutation in a letter. Use a colon to separate parts of a title, reference, or time value. Use a comma between two independent clauses in a compound sentence, joined by a coordinating conjunction. However, don t use a comma between short independent clauses joined by a coordinating conjunction, or after the conjunction. Use a comma to separate introductory phrases or clauses. Use a comma to separate three or more list items. Use the Oxford comma before the last list item. Use a comma to separate two or more adjectives of equal importance. Use commas to enclose parenthetical expressions or appositives. Use commas to enclose non-restrictive relative clauses and nonrestrictive phrases. Use commas to enclose absolute phrases. Use commas to enclose direct addresses, mild interjections, and examples introduced by such as, especially, particularly. Use commas to set off a direct quotation. 14

19 CHAPTER NINE PUNCTUATION Dash En ( ), Em ( ) Exclamation mark (!) Hyphen (-) Parentheses ( ) and brackets [ ] Period (.) Use a comma in place of understood words: She read Shakespeare; her husband, Freud. Use commas in dates and addresses. Don t use a comma to separate the subject and verb of the sentence. Don t use a comma to join independent clauses without a coordinating conjunction. Use an em dash to set off parenthetical information, such as an appositive. Use an em dash before the author s name after a direct quotation. Use an en dash in number ranges to replace the word to or from. Use an en dash in number ranges to contrast values or to illustrate a relationship between two things. Use an exclamation mark after an emphatic word, expression, or sentence. Don t use an exclamation mark after a mild interjection, more than one at a time, or with other stop marks. Use a hyphen to join compound words. Use a hyphen to join words used as a single adjective before a noun. Use a hyphen when writing out two-word numbers and two-word fractions. Use a hyphen with prefixes, such as ex-, self-, and all-, and with suffixes, such as-elect. Use a hyphen to divide a word at a syllable break when the word will not fit at the end of a line of text. Don t use hyphens as dashes. Use parentheses in pairs to set off incidental information. Use parentheses to enclose references or a question mark indicating doubt. Don t use parentheses to indicate deletion or to enclose editorial or explanatory comments. Use brackets in pairs to indicate editorial or explanatory comments. Use brackets with sic to indicate a printed error in a quotation. Use a period to conclude any sentence that isn t a direct question or an exclamation. Use periods with some abbreviations and people s initials. Use a period after a number or letter in a numbered list or formal outline. Use an ellipsis (three periods) to indicate the omission of words in a quote, or to show a break in thought. Don t use a period in the title of a work of art. 15

20 CHAPTER NINE PUNCTUATION Question mark (?) Use a question mark after a direct question. Use a question mark within parentheses to indicate doubt. Don t use a question mark after an indirect question or polite request in question form. Don t use a question mark within parentheses to express humour or irony. Quotation marks ( ) Use quotation marks to enclose a direct quotation, the titles of short written works, and words or letters used in a special sense. Use single quotation marks to enclose a quotation within a quotation. Always place periods and commas inside quotation marks. Always place colons or semicolons outside quotation marks. Place question marks, exclamation points, and dashes inside the quotation marks when they belong to the quotation and outside otherwise. Don t use quotation marks to enclose the title of an unpublished or long written work. Don t use quotation marks to enclose a word that is intended humorously or ironically. Semicolon (;) Use a semicolon between independent clauses in a compound sentence, not separated by a coordinating conjunction. Use a semicolon between independent clauses in a compound sentence, joined by a coordinating conjunction when there are commas in the clauses. Use a semicolon to separate items in a list when there are commas in some list items. Table 9: Usage of Punctuation Marks 16

21 CHAPTER TEN ILLUSTRATION Chapter 10 Illustration Illustrated text delivers information that is more immediately comprehensible to readers than non-illustrated text. Readers of all literacy levels respond to, and benefit from illustration, so long as it is well designed and properly incorporated into the text. Guidelines for Illustration The following list outlines some general guidelines concerning the use of illustration in technical documents: Illustrations detract from comprehension when they are merely decorative and don t convey worthwhile information. Illustrations and text must correspond and support each other. The text must introduce and explain the important points of the illustration, as the illustration must deliver what the text promises in an engaging presentation. The text and illustration must appear together, in space and time. When they are separated, such as text in the body and illustrations in the appendices, the correspondence is strained. As readers are drawn to illustrations, they will likely examine them before reading the introductory text that sets them in context. Therefore, title illustrations where it makes sense, and caption illustrations that aren t titled. Ensure the title or caption puts the illustration in context and highlights important information. Use line drawings to identify whole and parts. Three-dimensional drawings are best. Use pictures when more detail is required. But avoid excessive detail. Keep the reader focused on the task. Use structural illustrations when a flow of information is required. Use tables when precise individual values are required or need to be compared. Use graphs when the shape or relationship of values is required. In quantitative illustrations, highlight the data by enhancing the data ink and reducing the nondata ink. To make the quantitative illustrations easier to understand, group the data, prioritize the data, and sequence the data appropriately. 17

22 CHAPTER TEN ILLUSTRATION The Interaction of Text and Illustrations Text and illustrations interact in five ways, as outlined in Table 10. Use the following descriptions to help organize your illustrations in relation to your text and to achieve your desired impact. Method of Interaction Explanation Impact Complementary Juxtaposition Redundancy Stage Setting Supplementary Conveying different information where both channels are required to understand the key ideas. Conveying different information where the key ideas arise out of the clash or semantic tension between the ideas in each channel. Both channels convey the same key ideas. Best used with complex information. Conveying different information where one channel, usually the illustration, forecasts the key ideas and the other delivers the key ideas in full. Conveying different information where one channel predominates, providing the key ideas, while the other reinforces, elaborates, or instantiates these ideas. Constrains meaning. Gives readers pause and makes them rethink their position. Clarifies complex information and reinforces meaning. Stresses what is important. Subdivides and prioritizes meaning. Offers variety and an optional degree of depth to readers. Table 10: Interaction of Text and Illustrations 18

23 CHAPTER ELEVEN TABLES Chapter 11 Tables Use tables when precise, individual values are required or need to be compared. Guidelines for Table Style The following list outlines some general guidelines that should be applied to your table styles: Delineate columns and rows with blank space whenever possible. Otherwise, use subtle fill colours or subtle rules. Repeat column headings at the beginning of each subsequent page. Keep table structure consistent. Sort values in a meaningful order. Avoid text orientation other than horizontal, left to right. Align numbers on the decimal. Align dates to the centre, keeping them a consistent width. Align text to the left. Caption all tables, formatted as: Table #: Title. Locate the caption under the table, aligned left. Example Table with Formatting Table 11 provides an example of a preformatted table with generic entries describing each field. Number all tables sequentially throughout your document. Caption all tables using the format: Table #: Title. Locate the caption under the table, aligned left. Heading 1 (Bold) Entry 1 (Bold) Entry 2 (Bold) Heading 2 (Bold) Information regarding Entry 1 (Regular) Information regarding Entry 1 (Regular) Table 11: Example Table 19

24 CHAPTER TWELVE GRAPHS Chapter 12 Graphs Use graphs when the shape or relationship of values is required. Guidelines for Graph Style The following list outlines some general guidelines that should be incorporated into your graphs: Title and date the graph appropriately. Encode quantities to correspond accurately with the visual scale. Keep the distance between tick marks consistent with the quantitative values they represent. Include the value zero in the scale, or alert readers when you don t. However, always start the scale at zero for bar graphs. Label items on the graph, rather than using a legend. Avoid 3D displays of quantitative data. Example Graph with Formatting Figure 1 provides an example of a preformatted graph with generic entries describing each field. Number all graphs sequentially throughout your document. Caption all graphs using the format: Figure #: Title. Locate the caption under the table, aligned left East West North 0 1st Qtr 2nd Qtr 3rd Qtr 4th Qtr Figure 1: Example Graph 20

25 CHAPTER THIRTEEN CITATION AND REFERENCES Chapter 13 Citation and References Our citation and reference style is derived from the Chicago Manual of Style. We use the Author-Date format system, specifically. If in doubt concerning matters of citation and reference, consult the source text. Exemplary Citation The examples presented in Table _ illustrate citations using the author-date system. Each example of a reference list entry is accompanied by an example of a corresponding parenthetical citation in the text. These examples are taken directly from the Chicago-Style Citation Quick Guide, available for free online. Only a small sample is included here. Click the hyperlink for further examples. Source Type In-text Citation Reference List Entry Book (Pollan 2006, ) Pollan, Michael The Omnivore s Dilemma: A Natural History of Four Meals. New York: Penguin. Journal Article (Weinstein 2009, 440) Weinstein, Joshua I The Market in Plato s Republic. Classical Philology 104: Website (Google 2009) Google Google Privacy Policy. Last modified March Table 12: Chicago Author-Date Citation Style 21

26 INDEX Index Abbreviation, 7 Numbers, 9 A Acronym Abbreviation, 8 Ampere (A) Measurement, 10 Apostrophe ( ) Punctuation, 14 Apple Publications Style Guide Source Texts, 1 Average Statistics, 11 B Book Citation, 21 C -c- and s- Spelling, 4 Canadian Oxford Dictionary Source Texts, 1 Canadian Press Caps and Spelling Source Texts, 1 Canadian Press Stylebook Source Texts, 1 Candela (cd) Measurement, 10 Casual use Numbers, 9 Chicago Manual of Style Source Texts, 1 Colon (,) Punctuation, 14 Comma (,) Punctuation, 14 Common fractions less than one Numbers, 9 Common Word Abbreviation, 8 Companies Capitalization, 5 Currency D Dash Punctuation, 15 Date, Time, Year Numbers, 9 diphthongs Spelling, 4 double consonant Spelling, 4 E e + suffix Spelling, 4 Ethnicities Capitalization, 5 Exclamation mark (!) Punctuation, 15 F foreign plurals Spelling, 4 Formal Titles Capitalization, 6 G Government departments Capitalization, 5 H Hyphen (-) Punctuation, 15 I Initialism Abbreviation, 8 J Journal Article Citation, 21 22

27 INDEX K Kelvin (K) Measurement, 10 Kilogram (kg) Measurement, 10 L -l or ll Spelling, 4 Languages Capitalization, 5 Large numbers Numbers, 9 Lowercase and mixed-case Abbreviation, 7 M Mean Statistics, 11 Measurement Numbers, 9 Median Statistics, 11 Metre (m) Measurement, 10 Metric Symbols Abbreviation, 7 metric system Measurement, 10 Microsoft Manual of Style for Technical Publications Source Texts, 1 Mixed-case starting and ending with a capital letter Abbreviation, 7 Mode Statistics, 11 Mole (mol) Measurement, 10 N Nations Capitalization, 5 O Occupational Titles and Job Descriptions Capitalization, 6 -our Spelling, 4 P Parentheses ( ) and brackets [ ] Punctuation, 15 Per Capita Statistics, 12 Percent Change Statistics, 12 Period (.) Punctuation, 15 Places and Addresses Capitalization, 5 Proper names Capitalization, 5 Q Question mark (?) Punctuation, 16 Quotation marks ( ) Punctuation, 16 R -re Spelling, 4 Religions Capitalization, 5 S Score, Vote Numbers, 9 Second (s) Measurement, 10 Sequences of people or animals Numbers, 9 Single letter Abbreviation, 7 Standard Deviation Statistics, 12 Sun Technical Publications: A Style Guide for the Computer Industry Source Texts, 1 Suspension Abbreviation, 8 T Titles of Works Capitalization, 6 Trade names Capitalization, 5 W Website Citation, 21 Whole numbers greater than 10 Numbers, 9 Whole numbers less than 10 23

28