Transcript - STC India
Being Your Own Editor Richard H. Wallis STC India Bangalore and Mumbai January 2005 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Selected Topics in Editing • • • • • • • Slide 2 Hyphenation Dashes Subject-verb agreement Future tense Active and passive verbs Lists Clear and concise sentences © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Hyphenation: Overview Hyphens help ensure clarity and certainty in: • • Slide 3 Prefixes Compound modifiers © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Hyphenation: Prefixes With some prefixes, a hyphen is often mandatory to make the meaning clear and unambiguous: • • • • • Slide 4 recreation of code remarking the exams reformed rock band a cross section of users extra marital affair re-creation of code re-marking the exams re-formed rock band a cross-section of users extra-marital affair © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Hyphenation: Compound Modifiers If a noun is preceded by a two-word modifier, the modifier usually requires a hyphen: • a little used component • a little-used component • fifty odd engineers • fifty-odd engineers • zero filled sequence number • zero-filled sequence number Slide 5 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Hyphenation: Compound Modifiers In a compound modifier, do not insert a hyphen following an adverb that ends in -ly: • A fully loaded system is recommended. • Wi-fi gives you entirely new communication options. • Radically different times require new ideas. If a noun is followed by a two-word modifier, the modifier does not usually require a hyphen: • The string is case sensitive. • That component is little used. • The sequence number must be zero filled. Slide 6 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Selected Topics in Editing • • • • • • • Slide 7 Hyphenation Dashes Subject-verb agreement Future tense Active and passive verbs Lists Clear and concise sentences © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Dashes: Overview There are two types of dash: • En dash (–) – Longer than a hyphen (-) – Length of the letter N in the same font – Separates words in compounds – Divides numbers in a range • Em dash (—) – Twice the length of an en dash – Length of the letter M in the same font – Separates parts of a sentence Slide 8 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. En Dash The en dash has three basic functions: • Replaces the hyphen in compound adjectives when one or more elements are open (nonhypenated) two- or three-word elements – Gulf States–based company – The post–World War II economic boom – A New Delhi–New York collaboration • Substitutes for the word through in a range of inclusive numbers, letters, or months – See steps 1–6 – In the period 2004–2006 – January–March budget • Indicates negative number or subtraction (minus sign) Slide 9 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. En Dash: Examples • • • • • • • • • • • • Slide 10 Windows XP–compatible features A dialog box–type button A pre–Dreamweaver MX release Nobel Prize–winning scientist non–case sensitive string (incorrect) non-case-sensitive string Temperatures of less than –10ºC (no space) The value of x – y is 0. (space before and after) From pages 35–40 (incorrect) From pages 35 to 40 (or just “pages 35–40”) Between 2002–2005 (incorrect) Between 2002 and 2005 (or just “2002–2005”) © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Em Dash The em dash has one main function in technical writing: • Use an em dash to set off a phrase or clause requiring more emphasis than parentheses provide. – If those two teams—Brazil and Spain—play in the championship, TV ratings are sure to go up. – The dash can halt readers in their tracks—it makes them pay attention—as they scan your text. • Use no more than two em dashes in a single sentence. For other items that need to be set off, use parentheses or commas. • Do not use an em dash to introduce a definition, a subtitle, or a list. Use a colon instead. Slide 11 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Em Dash: Examples • • It is important—and often critical—to use the latest versions—RoboHelp X5 and WebWorks Publisher 2003—so that you have the most up-to-date features. It is important—and often critical—to use the latest versions (RoboHelp X5 and WebWorks Publisher 2003) so that you have the most up-to-date features. • • Setup task 2—Verifying the system requirements Setup task 2: Verifying the system requirements • • Setting Up Your E-mail—Example Setting Up Your E-Mail: Example Slide 12 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Selected Topics in Editing • • • • • • • Slide 13 Hyphenation Dashes Subject-verb agreement Future tense Active and passive verbs Lists Clear and concise sentences © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Subject-Verb Agreement: Overview Problems with subject-verb agreement occur because references to objects (or people) are not consistently singular or plural in the same sentence. • • • • • • • • Slide 14 Singular subjects take singular verbs. Plural subjects take plural verbs. The words all, any, some, none, and what can be either singular or plural. The words each, either, and every are singular. The phrase the number of is singular. The phrase a number of is plural. The phrases a kind of and a sort of are singular. The phrases kinds of and sorts of are plural. © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Singular Subjects with Singular Verbs • • • • • • • Slide 15 A summary of the targets’ availability and policy violations, as well as key metrics, are displayed. A summary of the targets’ availability and policy violations, as well as key metrics, is displayed. If a customer purchases $100 in services, they are entitled to a discount of 10%. A customer who purchases $100 in services is entitled to a discount of 10%. Customers who purchase $100 in services are entitled to a discount of 10%. The next topic that we cover are the many types of error messages. The next topic that we cover is the many types of error messages. © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Plural Subjects with Plural Verbs • • • • • • Slide 16 A host is a machine on which one or more managed services resides. A host is a machine on which one or more managed services reside. A number of new methods has been added to this interface. A number of new methods have been added to this interface. The supervisor notices what appears to be errors in the report. The supervisor notices what appear to be errors in the report. [what takes a plural verb in this sentence because it refers to the plural errors] © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Guidelines for Using the Word none • • • The word none can be either singular or plural. However, it is more likely to be plural. None does not always mean “not one.” In fact, the meaning of none is usually closer to “not any (of them).” If none means “not any (of them),” it takes a plural verb: – None of the workers are tired. [none of them] – Meaning: no individuals • If none means “none of it,” it takes a singular verb: – None of the memory is available. [none of it] – Meaning: no portion or amount Slide 17 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Using none: Examples • • • • • Slide 18 Verify that none of your students are using outdated textbooks. [none of them] None of the code was lost during the transfer. [none of it] None of the programmers (has/have) experience with Perl. None of the programmers have experience with Perl. [none of them] Not one of the programmers has experience with Perl. [for emphasis: not a single one] © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Selected Topics in Editing • • • • • • • Slide 19 Hyphenation Dashes Subject-verb agreement Future tense Active and passive verbs Lists Clear and concise sentences © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Future Tense: Overview • • • • • Slide 20 There is very rarely a need for future tense (will, shall) in technical writing. Use present tense to indicate the next step or action, the result of an action, or a continuing or repeating event. Use present tense in instructions and procedures. Present tense describes actions that are routine, always take place, or are expected to take place (even in the future). Use future tense only where necessary (for example, if you know that something will happen in an update or subsequent release). © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Avoiding Future Tense: Examples • • After you click Finish, the home page will appear. After you click Finish, the home page appears. • • Otherwise, an error will occur. Otherwise, an error occurs. • • The appendix for this book will cover: The appendix for this book covers: • Using additional resources will not provide extra benefit here. Using additional resources does not provide extra benefit here. • Slide 21 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Appropriate Use of Future Tense: Examples • • Slide 22 New diagnostic features will be available in future versions. The sign-on window requires a user name and password, which your instructor will provide. © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Selected Topics in Editing • • • • • • • Slide 23 Hyphenation Dashes Subject-verb agreement Future tense Active and Passive Verbs Lists Clear and concise sentences © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Types of Verbs We classify verbs based on the focus of the action in a sentence. • Active verbs – The subject of the sentence carries out the action of the verb. – Using active verbs is a way of focusing on the subject as the performer of the verb’s action. • Passive verbs – The subject of the sentence is the receiver of the action of the verb. – Using passive verbs is a way of focusing on the subject as the receiver of the verb’s action. Slide 24 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Active Verbs: Examples In the following “active” sentences, the subject is the performer of the action: • Users access their e-mail from the corporate portal page. – The subject of the sentence is Users. – The users carry out the action of accessing e-mail. • The server provides tools for developing and deploying applications. – The subject of the sentence is server. – The server carries out the action of providing tools. Slide 25 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Passive Verbs: Examples In the following “passive” sentences, the subject is the receiver of the action: • The values are returned when the request ends. – The subject of the sentence is values. – The values are the receiver of the action of “returning.” – The performer of the action of “returning” is unknown or unstated. Is it the system? • Spell-checking has been introduced in version 2. – The subject of the sentence is Spell-checking. – The spell-check feature is the receiver of the action of “introducing.” – The performer of the action of “introducing” is unknown or unstated. Who or what was it? Slide 26 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Passive Verbs: Example Who or what is the performer of the action in the following sentence? • Applications are accessed with the following code. – The subject of the sentence is Applications. – The passive verb is are accessed. – The performer of the action is _________. Slide 27 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. When Passive Verbs Are Okay It is acceptable to use passive verbs in the following situations: • When the context of the discussion makes it clear that the focus of the sentence should be on the receiver of the action rather than the performer • When the receiver of the action is more important than the performer • When the actual performer of the action is unknown or not important to the discussion • When you want to avoid making an inanimate object the performer of the action Slide 28 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Passive Verbs: Additional Examples How could you change the following sentences to include active verbs? • A mobile page is designed for display on mobile devices. • Our documentation is translated into various other languages. • Tools are provided for developing and deploying applications. • My brother was arrested yesterday for shoplifting. Slide 29 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Passive Verbs: Additional Examples How could you change the following sentences to include active verbs? • A mobile page is designed for display on mobile devices. • Our documentation is translated into various other languages. • Tools are provided for developing and deploying applications. • My brother was arrested yesterday for shoplifting. Changing these sentences to include active verbs requires the mention of a specific performer or agent, which is sometimes either not necessary or impossible. The sentences are fine as is. Slide 30 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Selected Topics in Editing • • • • • • • Slide 31 Hyphenation Dashes Subject-verb agreement Future tense Active and passive verbs Lists Clear and concise sentences © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Types of Lists There are two basic types of lists. • Bulleted list: an unordered list – The sequence of list items is not important. – Items are parallel in grammatical structure. – Items are not exhaustive. – There are at least two bulleted items in the list. • Numbered list: an ordered list (typically a procedure) – – – – – Slide 32 The sequence of list items is critical. Items are parallel in grammatical structure. All items are included. There are at least two numbered items in the list. In a procedure, a period concludes each numbered step. © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Tips for All Lists List items should be parallel in structure and grammar. Not Parallel Some of the benefits are: • In-memory querying support • Performance is better. • Tightly coupled interaction • Optimized Parallel Some of the benefits are: (all noun phrases) • In-memory querying support • Better performance • Tightly coupled interaction • Optimized transactions Slide 33 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Tips for Bulleted Lists The first bullet item should not be an introduction to the other items in the list. Incorrect • A top-of-the-line laptop computer • Guarantees fast Internet connections • Provides advanced graphic design capabilities • May be able to replace your desktop machine Correct A top-of-the-line laptop computer: • Guarantees fast Internet connections • Provides advanced graphic design capabilities • May be able to replace your desktop machine Slide 34 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Tips for Bulleted Lists Do not start list items with the same word or phrase. Redundant • page: This directive is used to define important attributes for a JSP. • include: This directive is used to include files in the current JSP. • taglib: This directive is used to specify custom markup tags. Improved • page: Defines important attributes for a JSP • include: Includes files in the current JSP • taglib: Specifies custom markup tags Slide 35 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Tips for Procedures Describe only one action (or two short and closely related actions) per step. Too many actions in one step 1. Select File > New and click the Memos tab. Then select Memo Wizard to preview , and select the Template option if you are satisfied 2. Click on OK. Improved 1. 2. 3. 4. Slide 36 Select File > New, and then click the Memos tab. Select Memo Wizard to preview it. If you are satisfied, select the Template option. Click OK. [never use click on or clicking on] © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Tips for Procedures Start a new (unnumbered) paragraph below a step if you want to add a result or explanation. Use a “soft return.” Action combined with result 1. Select the ZIP code from the drop-down list in the Postal Code field. If the ZIP code that you select has an optional four extra digits, the ZIP+4 window appears. 2. Enter the street address. Action separated from result 1. Select the ZIP code from the drop-down list in the Postal Code field. If the ZIP code that you select has an optional four extra digits, the ZIP+4 window appears. 2. Enter the street address. Slide 37 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Selected Topics in Editing • • • • • • • Slide 38 Hyphenation Dashes Subject-verb agreement Future tense Active and passive verbs Lists Clear and concise sentences © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Make Your Writing Concise and Clear To create text that is easy to read and understand: • Avoid lengthy, complex sentences – Transform a long sentence into shorter sentences – Transform a long sentence into a bulleted list • • • • • Slide 39 Provide important information first Eliminate unnecessary words and phrases Eliminate or simplify interruptions Break up noun strings Place modifiers near the words they modify © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Transform a Long Sentence into Shorter Sentences Slide 40 • For example, in a system that runs large OLTP jobs during the day that require large buffer caches and runs parallel batch jobs at night that require large values for the large pool, you must simultaneously configure both the buffer cache and the large pool to accommodate their peak requirements. [53 words] • For example, consider a system that runs large OLTP jobs during the day and parallel batch jobs at night. The OLTP jobs require large buffer caches; the batch jobs require large values for the large pool. You must simultaneously configure both the buffer cache and the large pool to accommodate their peak requirements. [54 words] © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Transform a Long Sentence into a Bulleted List Triggers execute implicitly when a data event such as DML on a table (an INSERT, UPDATE, or DELETE triggering statement), an INSTEAD OF trigger on a view, or data definition language (DDL) statements such as CREATE and ALTER are issued, no matter which user is connected or which application is used. [51 words] Slide 41 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Transform a Long Sentence into a Bulleted List Triggers execute implicitly when any of the following data events are issued: • DML on a table (an INSERT, UPDATE, or DELETE triggering statement) • An INSTEAD OF trigger on a view • Data definition language (DDL) statements, such as CREATE and ALTER This is the case no matter which user is connected or which application is used. [55 words] Slide 42 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Provide Important Information First • • • • • • Slide 43 The manager’s attempt to accelerate the production schedule for the beta release failed. The manager failed in her attempt to accelerate the production schedule for the beta release. The cost savings of having to maintain only a single IT support team are significant. There are significant cost savings in maintaining only a single IT support team. Changes to this process, which can result in delays and error messages, are not recommended by the developers. The developers do not recommend changes to this process, which can result in delays and error messages. © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Eliminate Unnecessary Words or Phrases • • • • • • Slide 44 The reason why there are two parent cursors instead of one is because their names are not identical. There are two parent cursors instead of one because their names are not identical. These components are what you use for editing code and for managing the user interface. Use these components to edit code and manage the user interface. It is essential that you understand who your users are and what your systems are comprised of. Understand your users and your systems. © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Eliminate or Simplify Interruptions Slide 45 • However, if, in a business situation, the application performs unsatisfactorily, the customer may request the services of a consultant. • However, the customer may request the services of a consultant if the application performs unsatisfactorily in a business situation. • The foreign key constraint enforcement, supplied by Microsoft, which does not use SQL, is fast, easy to declare, and does not create network traffic. • The Microsoft-supplied foreign key constraint enforcement (which does not use SQL) is fast, easy to declare, and does not create network traffic. • Microsoft supplies the foreign key constraint enforcement, which does not use SQL. It is fast, easy to declare, and does not create network traffic. © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Break Up Noun Strings • • • • Tomorrow we’ll have a spam reduction plan implementation meeting. Tomorrow we’ll have a meeting to implement a plan to reduce the amount of spam. The next step is identifying cluster configuration component functions in traces. The next step is identifying the functions of cluster configuration components in traces. • • Security Feature Benefits Example Benefits of Security Features: Example • • Human Resources Management Overview Human Resources Management: Overview Slide 46 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Place Modifiers Near the Words They Modify Try not to place the word only just before the verb: • This patch should only be installed when requested by your support team. • This patch should be installed only when requested by your support team. • • • • • Slide 47 You only need to specify a tracking number if you want to be sure a specific package can be traced. You need to specify a tracking number only if you want to be sure a specific package can be traced. This phone only accepts calls from local numbers. This phone accepts calls only from local numbers. This phone accepts calls from local numbers only. © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Place Modifiers Near the Words They Modify • • The server was expected to shut down after experiencing delays as early as tomorrow. After experiencing delays, the server was expected to shut down as early as tomorrow. • • Usually, that link is available on the portal page. That link is usually available on the portal page. • You can prevent attacks by hackers who attempt to access your network by using a secure firewall. • By using a secure firewall, you can prevent attacks by hackers who attempt to access your network. • Use a secure firewall to prevent attacks by hackers who attempt to access your network. Slide 48 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Tips for Self-Editing • • • • • • • Slide 49 Simplify! Being brief is good. In certain words with prefixes, insert a hyphen so that the meaning is clear and unambiguous. Reread sentences and fix any disagreement between subjects and verbs. Avoid sentences that are too long or complex. Divide them into shorter sentences. Consider using a bulleted list when you want to call attention to three or more items. Make sure that important information does not come at the end of a sentence. Place modifiers as close as possible to the words they modify. © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Questions, Problems, Comments, and Ideas… Richard H. Wallis [email protected] Slide 50 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved.