© 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Being Your Own Editor...

© 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved.

Being Your Own Editor

Richard H. Wallis

STC IndiaBangalore and Mumbai

January 2005

Slide 2 © 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved.

Selected Topics in Editing

• Hyphenation

• Dashes

• Subject-verb agreement

• Future tense

• Active and passive verbs

• Lists

• Clear and concise sentences


Hyphenation: Overview

• Prefixes

• Compound modifiers

Hyphens help ensure clarity and certainty in:


Hyphenation: Prefixes

• recreation of code

• remarking the exams

• reformed rock band

• a cross section of users

• extra marital affair

With some prefixes, a hyphen is often mandatory to make the meaning clear and unambiguous:

re-creation of code

re-marking the exams

re-formed rock band

a cross-section of users

extra-marital affair


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


Hyphenation: Compound Modifiers

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.

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.



• Hyphenation

• Dashes


• Future tense


• Lists



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


En DashThe 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)


En Dash: Examples

• 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”)


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.


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



• Hyphenation

• Dashes


• Future tense


• Lists



Subject-Verb Agreement: Overview

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

Problems with subject-verb agreement occur because references to objects (or people) are not consistently singular or plural in the same sentence.


Singular Subjects with Singular Verbs

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


Plural Subjects with Plural Verbs

• 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]


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 aplural 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


Using none: Examples

• 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]



• Hyphenation

• Dashes


• Future tense


• Lists



Future Tense: Overview

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


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.


Appropriate Use of Future Tense: Examples

• New diagnostic features will be available in future versions.

• The sign-on window requires a user name and password, which your instructor will provide.



• Hyphenation

• Dashes


• Future tense

• Active and Passive Verbs

• Lists



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.


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.


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?


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


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


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.


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.



• Hyphenation

• Dashes


• Future tense


• Lists



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


Tips for All ListsList 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


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


Tips for Bulleted ListsDo 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


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. Select File > New, and then click the Memos tab.

2. Select Memo Wizard to preview it.

3. If you are satisfied, select the Template option.

4. Click OK. [never use click on or clicking on]


Tips for ProceduresStart 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 thePostal Code field.If the ZIP code that you select has an optional fourextra digits, the ZIP+4 window appears.

2. Enter the street address.



• Hyphenation

• Dashes


• Future tense


• Lists



Make Your Writing Concise and Clear

• Avoid lengthy, complex sentences– Transform a long sentence into shorter sentences– Transform a long sentence into a bulleted list

• Provide important information first

• Eliminate unnecessary words and phrases

• Eliminate or simplify interruptions

• Break up noun strings

• Place modifiers near the words they modify

To create text that is easy to read and understand:


Transform a Long Sentenceinto Shorter Sentences

• 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]


Transform a Long Sentenceinto 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]


Transform a Long Sentenceinto 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]


Provide Important Information First• 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.


Eliminate Unnecessary Words or Phrases

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


Eliminate or Simplify Interruptions• 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.


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


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.

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


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.


Tips for Self-Editing

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


Richard H. Wallis

[email protected]

Questions, Problems, Comments, and Ideas…

Date post:	17-Dec-2015
Category:	Documents
Upload:	estella-hubbard
View:	214 times
Download:	0 times

© 2005 by Oracle Corporation and Richard H. Wallis. All rights reserved. Being Your Own Editor...

Documents