Writing Guidelines Lecture

8/12/2019 Writing Guidelines Lecture

1/15

2006-2011 Sharon Burton

Writing Guidelines for Eng 180

The standards you are

expected to follow for this class

Or -

Why you may hate us


2/15


3/15


Active voice

Active voice is critical to technical writing

Active voice depends on the subject, the actor

The actor comes first Passive voice:

The award was won by the writers.

Active voice

The writers won the award. Always write active voice

Practice with sentences that start You can


4/15


Present tense

English has 7 or 8 tenses

Other languages have more or less

We care most about present tense

It puts the action in the sentence in the now, making is relevantand immediate

Only use (simple) past or (simple) future tense when it reallyhappens then

Present tense

Bob runs to the car.

Past tense

Bob ran to the car.

Future tense

Bob will run to the car.


5/15


Second person

He, she, it, they, we, I, you

You is second person

Youre writing to a specific person

Dont use the user

Unless there is really a different group of users,

separate from your reader

Second person is also easier to read in

English

More familiar and trusted


6/15


User focused, user centric

Because we write to people, we need tokeep the focus on the user

Users need to care why they need to know thisinformation

They want to know what they can do or why thisis important to them

For example: InTouch uses tags to talk to other products.

You can use tags to let InTouch talk to otherproducts.


7/15


Actual Writing

Lets look at how to write like this

This is the writing we expect from you in this

class The writing style they taught you in the English

Department is bad

This is different than other classes

This is writing in the real world


8/15


Short is good

Short sentences are easier to understand

Fewer ideas in a short sentence

No more than 25 words per sentence

Short paragraphs

Paragraphs are groups of related sentences

No more than 3 to 5 sentences per paragraph

Short sections

Sections are groups of related paragraphs

No more than 3 to 5 paragraphs before a section heading


9/15


10/15


Building sentences and paragraphs

Paragraphs start with a topic sentence Topic sentences explain the point of the

paragraph. The user can read just the topic sentence and get the

idea of the entire paragraph

Sometimes you need two sentences to link twoideas together to help the user understand the

linkage as a topic sentence. You should never need more than two sentences

If you do, you dont understand what you are writingabout or you are not explaining it clearly


11/15


Sentences and paragraphs, cont

Other sentences in the paragraph amplify and

support the topic sentence

The paragraph can end with an example that illustrates the concept

with a limitation or special case the user should know now

that they know about the general class

Example Each type of tag has a set of unique properties. These properties are

defined in dotfields. Dotfields can access, monitor, and modify tag

properties. You can use dotfields to affect your animations by accessing

and modifying any of the numerous dotfields related to the tag selected.

Not all dotfields will work in all expressions.


12/15


Parsing the paragraph example

Each type of tag has a set of unique properties. These properties

are defined in dotfields.

Together, these are the topic sentence

The sentences could be combined to create one sentence but astwo sentences they contain one idea each

The end of the first sentence is repeated as the beginning of

the second sentence

Linking these sentences (and ideas) together

These sentences extend the information the user already has

S/he was told about tags in general and is now being told another

thing about tags.


13/15


Parsing example, cont

Dotfields can access, monitor, and modify tag properties. You canuse dotfields to affect your animations by accessing and modifyingany of the numerous dotfields related to the tag selected.

These sentences explain what the user can do withdotfields

The end of the second sentence is repeated as thebeginning of the third sentence, linking thesesentences (and ideas) together.

These sentences are user-focused They are written to the userthey tell him what he specifically

can use them for, not what the product uses them for.


14/15


Parsing example, cont

Not all dotfields will work in all expressions.

This sentence finishes the paragraph

Telling the user a limitation of the general class he learnedabout in the previous 2 sentences.

This sentence could address the question: Why did it

do that?

Notice that no sentence is longer than 25 words.

This example paragraph is 5 sentences, but the case can

be made that conceptually, the 2 topic sentences count as

one.


15/15

Documents

Writing Guidelines Lecture