Three Short Writing Tutorials

Presented by Elizabeth Wilcox

Introduction

• This is a series of short tutorials about topics that are relevant to Symantec information developers.

• You will have a chance to practice the topics presented in each tutorial.

Training Outline

Lesson 1: Writing effective stem sentences. Identify and correct nonconforming stem sentences so that they will pass acrocheck (and facilitate machine translation of your documentation).

Lesson 2: Avoiding comma misuse, including splices. Review when to (and not to) use commas.

Lesson 3: Using phrasal verbs correctly. Learn the difference between particles and prepositions, and apply what you have learned.

Lesson 1: Objectives

• Spot nonconforming stem sentences.

• Correct your own (or others’) stem sentences.

Lesson 1: Presentation. Introducing bulleted lists

From SymTOP Help:

Introduce every bulleted list that appears in body text in

one of the following ways:

– You can create resource associations in the following ways:

– Install the software as follows:

– Choose from the following options:

Lesson 1: Practice. Do these stem sentences conform?

Circle the bullet next to any stem sentence that conforms to the standard.

• Here is an example:

• These are some of your options:

• On the Users page, enter this information for each user:

• There are two ways to configure the server:

Lesson 1: Corrected stems

• Here is an example:

• These are some of your options:

• Enter this information for each user:

• There are two ways to configure the server:

• Refer to the following example:

• Choose from the following options:

• Enter the following information about each user:

• You can configure the server in the following ways:

Lesson 1: Wrap-up notes

The goal of stem sentences and bulleted lists:To make nonprocedural, nonsequential items easy to scan (from “About bulleted lists,” SymTOP Help).

Simplify the user’s cognitive task by introducing bulleted lists in a consistent manner throughout the documentation.

Simplify your writing tasks by writing conforming stem sentences that pass acrocheck.

Lesson 2: Objectives

• Recognize comma misuse, including splices, in your own or peers’ writing.

• Correct common comma errors.

Lesson 2: Presentation. Using commas correctlySeparators set off two

independent clauses (complete sentences).

Introducers separate a dependent clause (DC) from the following independent clause (IC). (Omit the comma if the IC precedes the DC.)

Inserters set off nonessential sentence elements.

Serial commas separate items in a series.

I set up the system, and he is doing the installation.

Even though this list is incomplete, you will have a good idea of how to use commas in specific instances.

The user, however, defines organizational groups.

Set up, install, and then test your site servers.

Lesson 2: Practice. Correct these common comma errors Comma between two

nouns or noun phrases in a compound object

Comma between two verbs or verb phrases in a compound predicate

Comma splice (when a comma is used in place of a stronger break)

X: Make sure that the cables are connected, and that the computer is turned on. Solution? ______________________________________________________________________

X: Package services run on site servers, and offload programming from the primary platform server.Solution? _________________________________________________________________________

X: Install the server, check the installationSolution? __________________________________________________________________________

Lesson 2: Wrap-up notes

• Use commas on purpose (not out of habit).

• If you do not know why you need a comma or cannot explain why it should be there, it probably does not belong.

Lesson 3: Objectives

• Recognize phrasal verbs.

• Use phrasal verbs correctly by not combining the particle with a following preposition.

Lesson 3: Presentation

Phrasal verbs are those that are composed of two words. Look at the following examples:◦ Log on to the server.◦ Turn in your status report.◦ Can you break it down?◦ Turn the volume up.

Phrasal verbs contain a main verb and a particle (the small word), as in “log on” and “break down.”

The particle in a phrasal verb is not a preposition, even though in some phrasal verbs it may look like one (for example, “in” or “on”).

Lesson 3: Practice. Circle the correct use in each pair.

oLog on to the server.

Turn your status report in to your supervisor.

Can you break down the problem?

Shutdown the server.

oLog onto the server.

Turn your status report into your supervisor.

Breakdown the problem.

Shut down the server.

Lesson 3: Review

• Just because two words next to each other (such as “on” and “to”) sometimes function as one (“onto”) does not mean that they should be run together as one in every instance. Evaluate each instance, and distinguish particles from prepositions.

Test it: Can you insert a pronoun between the alleged verb and its particle and retain a logical sentence? If so, you are likely looking at a phrasal verb. In that case, keep the preposition separate from the verb’s particle.◦ Log her on to the server. (The verb is phrasal: log on.)◦ Turn it in to your manager. (The verb is phrasal: turn in.)

Summary• Lesson 1: Follow the SymTOP guidelines to write conforming

stem sentences.

• Lesson 2: Use commas on purpose. If you cannot see the purpose for inserting a comma, omit it or ask an editor for help.

• Lesson 3: Separate particles (“on,” “in”) from prepositions (“to”).

• Resources

– In Vasont, click SymTOP Help. Search for “stem sentences” and other topics.

– Source: See “The Purdue Online Writing Lab (OWL)” site at http://owl.english.purdue.edu/owl/resource/607/02/ for excellent information about commas, pronouns, and other tricky topics.

Evaluation

Please evaluate the value of this training or future,

similar training.

Did this short training help alert you to any potential trouble spots (or do you already watch out for these)?

Do you want additional training about any of the tutorial topics? If so, please notify Liz.