tech writing w rks hp

7/28/2019 Tech Writing w Rks Hp

http://slidepdf.com/reader/full/tech-writing-w-rks-hp 1/82

Technical Writing and

Readability and Style

By

Dr. Rami Oweis

Jordan University of Science andTechnology



PART ONE. INTRODUCTION

Why Study Technical andProfessional Communication?Even the most brilliant professionals

(scientists, engineers, managers, …etc.)must have the ability to convinceothers (coworkers, clients, supervisors,… etc.) of their worth.

Good teamwork is impossible withoutgood communication.



Introduction (Cont’d.)

For many professionals, the end

product of their work is a written

document.

The more your progress, the more

important communication becomes.



IMPORTANCE

Many well-structured surveysindicate that communication skillsrank very high in importance toindividuals' careers. They even rank

higher than technical skills.

Such skills include public speaking,

working with individuals, workingwith groups, and talking with people.



Importance (cont’d.)

Surveys indicate that writing is one of the most important communicationskills.

In addition to writing, oralcommunication skills are equally

important including conversing,interviewing, listening, and giving oralpresentations.



Importance (Cont’d.)

In a diverse and globalized world, take intoaccount the ethical and social aspects of communication plus its international nature.

In a diverse and globalized world, take into

account the collaborative nature of communication among different people.



Importance (Cont’d.)

In a diverse and globalized world, takeinto account the computerization of technical communication documents.

Surveys showed that about 1/4 of professionals' time is spent on

communication.



Forms of Communication The written formof communication: memos, letters,reports, procedures, proposals, …).

The oral formof communication: one-to-one talks,

telephone calls, small group or committee meetings.

Most professional need both forms.

Writing clearly is on the top of the list of all skills

needed.



Complexity

Why professionals communicatebadly? Partlydue to poor training!

Communication is different fromtechnical training-two different

languages.

Why professionals communicate badly,

again? Mainlydue to cognitive and

physical complexity of the process.



Skills in Problem Solving and

Communication A problem is a conflict between whatshould be(the desired) and what is (theactual).

Problems can be either well-defined(one correct solution) or ill-defined.The latter requires good

communication skills.



Skills in Problem Solving and

Communication (Cont’d.)

People, unlike machines, interpret infonot merely pass it. Thus, consider thedifferent backgrounds and socially

negotiate a solution (intellectual skills).

In addition, project management skills

are needed for the communicationproduct: resources, timing, deadlines,cooperation and coordination, …



PART TWO. GENERAL

WRITING STRATEGIES

GENERATING IDEAS

(Invention, or Prewriting)

Problem DefinitionFirst of all, identify the problem (ex. a job letter) AND how you are supposedto address it (your task and role).



General Writing Strategies

(Cont’d.)

Brainstorming

Just write down whatever comes intoyour head about the topic (no good,

incomplete, inadequate ----- later) .The purpose: stimulate your thinkingand generate ideas.

Best done in collaboration with otherpeople. At this stage, don't criticize orevaluate ideas!



Using Systematic Questions After brainstorming, try a moresystematic approach of thinking orexploring the subject (all relevantmaterial).

Relevant material arises fromexploring: the subject matter, subjectrequirements, type of writing,

audience, and institutional concerns.Exploring each of these (askingquestions about the subject) willgenerate ideas.



Using Social and Ethical

Considerations for Audience

Impacts

Cooperate with many others to avoid

problems (insensitivity,…) Use the info completely, accurately, and

impartially (no bias) with good intention.

Finding Information* Besides the ideas you have so far

generated, search for further info in

libraries, dBases, …



Forming a Thesis (Point of

View)

Comes after the topic is explored,

questions answered, and ideas

generated.

Identify the main point you want to

make.

Once the main point is identified, the

rest of ideas should be organized to

support the main point.

Organization may be achieved by

outlines or idea diagrams.



Identifying Audiences and

Purposes: Who? Why communicating? What

they expect/hope?

AudiencesLearn to write to the audience (not to

yourself!)

The first audience you have written for wasone ideal reader (your teacher!)

Real-world audiences are different: consist of variety of readers, multiple audiences, knowless than you do (must explain), differ intheir reading strategies, will exert no effort tofigure out the unclear.



Major Types of Audiences

Managerial, Nonspecialist, Peer,International, and Mixed.

Managerial Audiences (Managers -

Decisions Makers).Make key informational maximallyaccessible by foregrounding it: that is,

put it up front so that managers caneasily find it. Managers tend to ignoredetails.



Audience Types (Cont’d.)

Nonspecialist Audiences: Whenever onereads something out of their field (Aproposal, an instruction manual, … etc.).

Basic rules:

Use as much common knowledge aspossible.

Provide an overview at the beginning.

Provide some background information.

Use lots of explanations and definitions byusing short paraphrases in parentheses(ex. hypertension – high blood pressure).

Use carefully chosen examples, analogies

and illustrations.




Peer Audiences: Writing to peers (co-workers, colleagues) who know about thesubject as much as you do (experts). Basicrules are:

Speak the same language as peers – Standard terms, conventional format,data display, …

Avoid going into tiny details and

explanations (examples, illustrations, ..)Make main point clear. In addition,however, emphasize details on data thatyou anticipate your peers are likely to

look at.




International Audiences: (nonnative)

Avoid long and complicatedsentences.

Avoid idiomatic vocabulary (slang,multiword, and culture-specific).

Try to use visual aids rather thanverbal explanations.




Mixed Audiences: consist of a mix of

all above (managerial, technical,

native, nonnative, …). Two basic ways:

- Layered document: different sections

are aimed at different audiences.

- Democratized document: all

audiences understand all parts.



Audience Analysis Identify audience characteristics and

needs for effective communication

(what info needed and how it is

presented).

A five-step procedure



Audience Analysis (Cont’d.)

Five steps:

1. Identify the communication's usesand the routes it will travel.

2. Identify all possible audiences,current or future, in or out of theorganization.

3. Identify the concerns, goal, values

and needs of each audience(Different departments inorganizations).



Audience Analysis (Cont’d.)

4. Make communication appropriate

(accessible and useful) for (busy)

mangers (integration of many

perspectives and goals).

5. Identify each audience's

preferences for and objections to the

arguments (esp. competitors andcritics).



Purposes

By doing all the above in the writingprocess, you have likely formulated aclear sense of purpose.

All communication is purpose-driven:

writers and readers, speakers andlisteners.

Make your purpose clear to the audienceto convey your message easily.

Emphasize the ostensible (dictated by thesituation) purposes and deemphasizeunstated purposes.



Constructing Arguments

As a technical professional, you don't

simply report info, rather, you exercise

judgment, make recommendations,

and propose solutions. Thus, you haveto be persuasive.

To be persuasive, you have to master a

minimum level of argumentation skills.



Constructing Arguments

(Cont’d.)

Argument as used here is intended to

mean a claim that something should be

believed or done with proof or reasons

for believing or doing it. However,argument in the sense of quarrels anddebates should be avoided.

The first step in making an effective

argument is to describe the problem

that the reader wants to have solved.



Basic Strategies of Argument Three main strategies or bases of

argument (Aristotle):

1. Logic and reason,

2. Credentials and character of the

communicator, and

3. Emotion

Generally, mix the three.



Argument Types

Two main types:

The argument of fact is about

something that exists (is, are/not).

The argument of policy that something

should be done (should/not).



The Argument of Fact Can be derived from three sources:

Questions or subarguments of

Existence

Q/S of Definition, and

Q/S of Quality.

If one of these fails, the main argument

fails.



The Argument of Fact

Ex. Want to argue that a manufacturershould be stopped from dischargingpollutants into public water.

Q of E: Is the company (not any other one)

discharging materials (any materials) intowater?

Q of D: Are the discharged materialsdangerous (regardless of amounts)?

Q of Q: Are the discharged materials presentin illegal or unsafe amounts?



The Argument of Policy Can be derived from two sources:

Questions or subarguments of Worth orGoodness (merit), and

Q/S of Expediency, Advantage, or Use.

Arguments based on the second sourceare much more successful than those

based on the first.



The Argument of Policy

Ex. A company intends to make falseclaims about the merits of heir productfor more sales. YOU want to argue that

the company should make honestclaims only.

Q of W&G: It is good and worthy to behonest.

Q of EAU: Advantageous for thecompany to have a reputation of honesty; Such honesty protects from

lawsuits, fraud charges, penalties, .… .



Relationship between Argument

Types

You can make an argument of fact

only. However, if you are making an

argument of policy, you will have to

establish all parts of the argument of fact first.



Building a Case

HOW to present/organize/plan the

whole communication.

Table 1 outlines the items of building a

case.

You’ve gotta be persuasive.

To be persuasive, make sure that you

link arguments together.



Building a Case (Cont’d.)

To link arguments, six major strategies:Simple Problem-Solution: Good foruninformed but very weak for the

informed). No need to state judgment criteria or evaluatecompeting solutions.

Criteria: Here, criteria must be

explicit and must be emphasized. Tobe acceptable, the criteria must becorrectand complete.




Chain of Reasoning: Here, arguments

are linked in a sequence of logical steps

proceeding from the more acceptable

claims to the more controversial. Thisis a highly analytical and deliberate

form, needs a committed and patient

audience. Effective for hostile andskeptical audiences.




Process of Elimination: Present a

number of solutions and gradually

eliminate all but one based on

specific criteria.

Experimental Research (Journal

article): Consists of four parts:

Problem, Method, Results, andDiscussion.



Whistleblowing

What a professional should do when

faced with an ethical dilemma (asked to

violate ethical standards)?

Go within the normal chain of

command.



Whistleblowing

If this doesn't work, go public (blow the

whistle) when the following conditions

are met (all need ability to build a case –

i.e., argue):

Deciding the harm is serious

Making concerns known to superiors

Having documented evidence

Having evidence that going public will

prevent the harm



Stating Problems

Problem Introduction

An excellent way to capture youraudience's attention is to startyourcommunication with an interesting

statement of the problem(indicatesproblem magnitude).

A problem can best be stated in the

form of two directly conflicting terms joined by a word signaling the conflict(the A-but-B style – the full form).

St t d P



Strategy and Purpose

Identification

After establishing a problem, the twoother steps (to show that your

communication addresses the problem)

are:

State the question(s) or task you're

addressing (identify strategy,

indicate missing info).

Announce the purpose of the

communication.

Sh t F f P bl



Short Form of Problem

Statement Common in science and techno logycommunications with the steps:

Explicit problem statement (A and butareimplied – one missing!)

Ex. Observed high mortality of the 2-year-old pines during the 2006 visit and expectedshortage in 2007.

The A-but-B format: the above is B. A is

implied that one does not want highmortality …

Question/ task

purpose



Drafting

First Draft

Goal of first draft is to turn ideas and

arguments into a text.

If all the above is worked out, writing a

first draft (rough) is relatively easy.

Never attempt to get the perfectdraft

form the first attempt. It fails! It

results in the “writer's block.”



Writer’s Block To overcome writer's block, steps andapproaches:

Write an outline and flesh it out inany way comfortable for u.

Sit down and write whatever comesinto your head about the topic.

Sit down and write different versions

of what you want to say until youlike something enough to improve it.

Talk about your subject to othersand why it is important then use it.



Testing and Revising

Both are essential parts of the writing

process (quality control) and work in a

cyclic manner (i.e., test, revise, then,

test, …).

The extent to which a document has to

be tested and revised depends on how

important it is.



Testing

Field testing- have a representative of the intended readers look at the

document.

Role playing- have a well selectedfriend play the role of the intended

reader.

Self-evaluation- do the role playing

yourself (sleep on it).



Testing (Cont’d.)

Two types of testingdepending on the

intended use of the document:

Testing of expositorywriting: when the

writer's goal is to inform the reader

about a topic or argue a case (letters,

proposals, reports, journal articles, …

etc.). It has a hierarchical structurewith few claims (main points) and lends

itself to selective reading.



Testing (Cont’d.)

A procedure for testing expository

writing is outlined as follows:

1. Give your reader(s) a copy and

encourage them to be critical and

don't bias them in any way.

2. Realize that readers differ in what they

look for (ideas, details, grammar, …)

3. Look at their comments and

understand them.



Testing (Cont’d.)

4. Ask questions about specific features

of the document (clarity of main points,

support of main points, mistakes in

details, anything offensive to readers,overall look, readability and flow, and

misspelling and grammar).



Testing (Cont’d.)

Testing of procedural writing: refers to

"how-to" documents such as tutorials,

manuals, … etc. where the writer's

goal is to get the reader follow a step-by-step procedure.



Revising

Revising follows testing with the

following key principles:

Make major repairs before minor

ones (never the reverse).

Fix up the content before you fix up

the form (content more important).

PART THREE VISUAL



PART THREE. VISUAL

ELEMENTS

So far we have covered the production

of words (written or spoken)

In many cases, words alone can't

transfer info or view points

Combine words with visual elements

(formatting and visual aids)

The latter includes drawings, figures,

charts, graphs, …

VISUAL ELEMENTS



VISUAL ELEMENTS

(Cont’d.)

Adding visual elements increases the

strength and memorability of messages

Visual elements presents a compact

form (A picture = 1000 words)

Thus, a communicator is ought to use

them effectively meaning

How to make an effective VA

When to use it

How to select the best type

How to integrate it into the text



Selecting Visual Elements

When to Use Visual Aid?

After making a good VA (nicely arranging

the info), three principles as to when to use

the VA:

When words alone are insufficient

When a compact summary is needed or

important info is to be highlighted

When it is conventional or easy to use aVA (budget calcs, architectural plans,

geographical locations, electric circuits, …



Selecting the Best Visual Aid

Line graphs: show well continuity and

direction. Weak with many lines and

intersections.

Bar graphs: Show well discreteness of

points and relationships, contrasts,

similarities, and differences among

many items.

Pie diagrams: show well relationships

among many items that total 100%.

Poor at showing differences.





(Cont’d.)

Tables: well for presenting lots of data

and giving absolute values. Poor at

showing trends. Least appealing.

Photographs: Good when no resources

to make a good line drawing, when

emphasizing the external appearance(x- section).





(Cont’d.)

Line drawings: these include several

types of drawings that focus on

external appearance, physical shape,

function, or relationship such assimplified photos, maps, anatomical

drawings, parts, models, objects, … .

C i i



Creating Visual Elements

Designing the Visual AidDesign such that the VA is relevant,clear, and truthful. All make it

independent. Relevant: make it emphasize the point

you want to make by choosing the best

type and including key info.





(Cont’d.)

Truthful: False or misleading VAs may

be created by

Inadvertently selecting the wrong

type of VA, or

Deliberately falsifying the data

(playing with the scale or

suppressing the zero).





(Cont’d.)

Clear: Conceptuallyand technically.

Conceptuallyclear entails a clearlydefined and relevant point in a good

form. Technicallyclear entails the necessityof informative and appropriate titles,labels, white space (making it notcluttered or crowded by eliminatingunnecessary details), …



Integrating the Aid into Text

Decide where best to use the VA (must

be tied to text).

Explain its main point and any

implications the reader should note.

Formatting VA to Make Reading



Formatting VA to Make Reading

Easier

Main relevant formatting features totechnical writing include:

Informative headings at the

beginningSingle spacing (or, double)

Short paragraphs

ListsNumbers to mark various

paragraphs

Liberal use of white space

PART FOUR



PART FOUR.

SPECIFIC APPLICATIONS

I. Resumesand J ob Letters A good Resume or job letter requires that

you know what you want to do by

Setting your goals (short- and long-term

ones), capabilities (studying, working,

playing, living, other special, …. ), and

constraints.

It also requires knowing what the

company does and offers. Look for info

everywhere (friends, library, … ).

Wh M k G d A li ?



What Makes a Good Applicant? The regular characteristics: welltrained, competent, smart,

hardworking, reliable, honest, good

communicator, ….

Take the cover letter and resume as a

chance to demonstrate how well you

can write (communication skills).

Technical qualifications are

determined by other hiring parts

(interviews, tests, reference letters, )

W i i G d J b L



Writing a Good Job Letter

Use a conventional format (look).Stress what you can do for the company,not what the company can offer you.

Address the person having the authority.

Stress (with evidence) youraccomplishments and responsibilitiesusing dynamic verbs like devised,organized, supervised, improved, created,

and developed.Make it look beautiful by avoidingspelling mistakes, typos, ….. That is, verycareful proofreading.

i i f i i



Designing Letter of Application Usually one page long with four mainsections:

The heading: includes writer's andreader's addressesand date.

A first paragraph that:

Introduces you (with an impressivereference).

Establishes the company's need andyour ability to fill it, or,

Establishes the reason for writing andyour request from the reader.

Designing Letter of Application



Designing Letter of Application

(Cont’d.)

A second (or several) paragraph (s) that:

Establish your most relevant experience and

qualifications.

Stress your accomplishments,responsibilities, and work qualities (with

evidence of good job) in addition to activities.

A closing paragraph that:

Gives any other pertinent data.

Asks for an interview and provides contact

info.

Designing the Resume



Designing the Resume A resume is a summary of all one's

activities and experience.

It must be as strong and impressive as

possible.

Characteristics:

Easy to read, not too long, not too

short, well formatted.

Give your vital statistics.



Designing the Resume (Cont’d.)

Should suggest where you are

heading in your career (Career

Goals section) and where you

have been (Work and Education section).

Must have a References section.

i



I I. Business Letters

Required for requesting info, ordering

equipment, supplies, praising or

thanking, complaining, responding, ….

It is characterized by being personal

with frequent use of such pronouns as

I , we, and you.

B siness Letters (Cont’d )



Business Letters (Cont’d.)

In writing a letter, the following steps (all

require you to generate ideas, analyze the

audience, and define your problem):

Orient the reader to the topic at hand

(new topic; reminder)Explain why the writer is writing



Business Letters (Cont’d.)

Provide enough info so that the

reader understands what to do.

Make sure to use the correct form of

salutation (address-Dear ….).

Avoid sexism (use Ms.; whole name;

to-from form, … etc.).

i



Basic Letter Formats

Three basic formats:

The Unblocked Format

The Semiblocked Format

The Blocked Format

(See the models provided)

I I I R t B i F t



I I I . Reports Basic Features

Generally, reports are read by mixedaudiences and thus should be accessibleto them and responsive to their needs.

The responsiveness may be increasedby two structural features of a report,

The Argumentative Structure, which isappropriate for managers (they see theinfo they need up front). The twofeatures are

TheArgumentativeStructure



The Argumentative Structure

The Foreword and Summary (orcounterparts): at the beginning formanagerial and nonspecialist readers,

followed by Discussion of details (that

support the proposed solution) for

technical readers.

The placement of generalizations

(Claims in the F&S) before their

support (Details in the D), which

represents the general report structure.

Purposes of the Foreword



Purposes of the Foreword

To catch the reader's attention: Whythe report was done and why it isimportant.

To quickly orient the audience to the

subject of the report (what wasdone).

To define the purpose or focus of thereport (predict what info the reportwill present).

F d (C ’d )



Foreword (Cont’d.)

An effective foreword (problem

setup) provides the driving force and

overall organizational structure of

the report.




g

(Cont’d.)

The Summaryprovides a compact

statement of results, conclusions and

recommendations (identifies the

solution to the problem).The purposes of the Summary are

To quickly present the results of the

project

To quickly present the important

recommendations and implications

of the project.




g

(Cont’d.)

Technical Discussions (details) for

specialist readers followed by

Appendixes of nonessential or lengthy

details.

R t St t



Report Structures

The Narrative (Chronological)Structure: found in lab and research

reports and journal articles. Presents

info in the chronological order itoccurred.

tech writing w rks hp

Documents