Technical Writing and Readability and Style

By Dr. Rami Oweis Jordan University of Science and Technology

PART ONE. INTRODUCTION Why Study Technical and Professional Communication?

Even the most brilliant professionals (scientists, engineers, managers, etc.) must have the ability to convince others (coworkers, clients, supervisors, etc.) of their worth.

Good teamwork is impossible without good communication.

Introduction (Contd.)
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 surveys indicate that communication skills rank very high in importance to individuals' careers. They even rank higher than technical skills. Such skills include public speaking, working with individuals, working with groups, and talking with people.

Importance (contd.)
Surveys indicate that writing is one of the most important communication skills. In addition to writing, oral communication skills are equally important including conversing, interviewing, listening, and giving oral presentations.

Importance (Contd.)
In a diverse and globalized world, take into account 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 (Contd.)
In a diverse and globalized world, take into 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 form of communication: memos, letters, reports, procedures, proposals, ). The oral form of 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 communicate badly? Partly due to poor training! Communication is different from technical training-two different languages.

Why professionals communicate badly, again? Mainly due to cognitive and physical complexity of the process.

Skills in Problem Solving and Communication

A problem is a conflict between what

should be (the desired) and what is (the actual). Problems can be either well-defined (one correct solution) or ill-defined. The latter requires good communication skills.

Skills in Problem Solving and Communication (Contd.)

People, unlike machines, interpret info not merely pass it. Thus, consider the different backgrounds and socially negotiate a solution (intellectual skills). In addition, project management skills are needed for the communication product: resources, timing, deadlines, cooperation and coordination,

PART TWO. GENERAL WRITING STRATEGIES

GENERATING IDEAS (Invention, or Prewriting) Problem Definition First of all, identify the problem (ex. a job letter) AND how you are supposed to address it (your task and role).

General Writing Strategies (Contd.)

Brainstorming Just write down whatever comes into your head about the topic (no good, incomplete, inadequate ----- later) . The purpose: stimulate your thinking and generate ideas. Best done in collaboration with other people. At this stage, don't criticize or evaluate ideas!

Using Systematic Questions

After brainstorming, try a more systematic approach of thinking or exploring the subject (all relevant material). Relevant material arises from exploring: the subject matter, subject requirements, type of writing, audience, and institutional concerns. Exploring each of these (asking questions about the subject) will generate 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?

Audiences
Learn to write to the audience (not to yourself!) The first audience you have written for was one ideal reader (your teacher!) Real-world audiences are different: consist of variety of readers, multiple audiences, know less than you do (must explain), differ in their reading strategies, will exert no effort to figure out the unclear.

Major Types of Audiences

Managerial, Nonspecialist, Peer, International, and Mixed. Managerial Audiences (Managers Decisions Makers). Make key informational maximally accessible by foregrounding it: that is, put it up front so that managers can easily find it. Managers tend to ignore details.

Audience Types (Contd.)

Nonspecialist Audiences: Whenever one reads something out of their field (A proposal, an instruction manual, etc.). Basic rules: Use as much common knowledge as possible. Provide an overview at the beginning. Provide some background information. Use lots of explanations and definitions by using short paraphrases in parentheses (ex. hypertension high blood pressure). Use carefully chosen examples, analogies and illustrations.

Audience Types (Contd.)

Peer Audiences: Writing to peers (coworkers, colleagues) who know about the subject as much as you do (experts). Basic rules 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 that you anticipate your peers are likely to look at.

Audience Types (Contd.)

International Audiences: (nonnative) Avoid long and complicated sentences. Avoid idiomatic vocabulary (slang, multiword, and culture-specific). Try to use visual aids rather than verbal explanations.

Audience Types (Contd.)

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 (Contd.)

Five steps: 1. Identify the communication's uses and the routes it will travel. 2. Identify all possible audiences, current or future, in or out of the organization. 3. Identify the concerns, goal, values and needs of each audience (Different departments in organizations).

Audience Analysis (Contd.)

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 and critics).

Purposes
By doing all the above in the writing process, you have likely formulated a clear sense of purpose. All communication is purpose-driven: writers and readers, speakers and listeners. Make your purpose clear to the audience to convey your message easily. Emphasize the ostensible (dictated by the situation) purposes and deemphasize unstated purposes.

Constructing Arguments
As a technical professional, you don't simply report info, rather, you exercise judgment, make recommendations, and propose solutions. Thus, you have to be persuasive. To be persuasive, you have to master a minimum level of argumentation skills.

Constructing Arguments (Contd.)

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 and debates 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 manufacturer should be stopped from discharging pollutants into public water. Q of E: Is the company (not any other one) discharging materials (any materials) into water? Q of D: Are the discharged materials dangerous (regardless of amounts)? Q of Q: Are the discharged materials present in illegal or unsafe amounts?

The Argument of Policy

Can be derived from two sources: Questions or subarguments of Worth or Goodness (merit), and Q/S of Expediency, Advantage, or Use. Arguments based on the second source are much more successful than those based on the first.

The Argument of Policy

Ex. A company intends to make false claims about the merits of heir product for more sales. YOU want to argue that the company should make honest claims only. Q of W&G: It is good and worthy to be honest. Q of EAU: Advantageous for the company 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. Youve gotta be persuasive. To be persuasive, make sure that you link arguments together.

Building a Case (Contd.)

To link arguments, six major strategies: Simple Problem-Solution: Good for uninformed but very weak for the informed). No need to state judgment criteria or evaluate competing solutions. Criteria: Here, criteria must be explicit and must be emphasized. To be acceptable, the criteria must be correct and complete.

Building a Case (Contd.)

Chain of Reasoning: Here, arguments are linked in a sequence of logical steps proceeding from the more acceptable claims to the more controversial. This is a highly analytical and deliberate form, needs a committed and patient audience. Effective for hostile and skeptical audiences.

Building a Case (Contd.)

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, and Discussion.

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 your audience's attention is to start your communication with an interesting statement of the problem (indicates problem 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).

Strategy and Purpose Identification

After establishing a problem, the two other 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.

Short Form of Problem Statement

Common in science and techno logy communications with the steps: Explicit problem statement (A and but are implied one missing!) Ex. Observed high mortality of the 2-yearold pines during the 2006 visit and expected shortage in 2007. The A-but-B format: the above is B. A is implied that one does not want high mortality 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 perfect draft form the first attempt. It fails! It results in the writer's block.

Writers Block
To overcome writer's block, steps and approaches: Write an outline and flesh it out in any way comfortable for u. Sit down and write whatever comes into your head about the topic. Sit down and write different versions of what you want to say until you like something enough to improve it. Talk about your subject to others and 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 selected friend play the role of the intended reader. Self-evaluation- do the role playing yourself (sleep on it).

Testing (Contd.)
Two types of testing depending on the intended use of the document: Testing of expository writing: 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 structure with few claims (main points) and lends itself to selective reading.

Testing (Contd.)
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 (Contd.)
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 (Contd.)
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 stepby-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 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 (Contd.)

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 a VA (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.

Selecting the Best Visual Aid (Contd.)

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

Selecting the Best Visual Aid (Contd.)

Line drawings: these include several types of drawings that focus on external appearance, physical shape, function, or relationship such as simplified photos, maps, anatomical drawings, parts, models, objects, .

Creating Visual Elements

Designing the Visual Aid Design 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.

Creating Visual Elements (Contd.)

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

Creating Visual Elements (Contd.)

Clear: Conceptually and technically. Conceptually clear entails a clearly defined and relevant point in a good form. Technically clear entails the necessity of informative and appropriate titles, labels, white space (making it not cluttered or crowded by eliminating unnecessary 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 Easier

Main relevant formatting features to technical writing include: Informative headings at the beginning Single spacing (or, double) Short paragraphs Lists Numbers to mark various paragraphs Liberal use of white space

PART FOUR. SPECIFIC APPLICATIONS

I. Resumes and Job 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, ).

What Makes a Good Applicant?

The regular characteristics: well trained, 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, )

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) your accomplishments and responsibilities using dynamic verbs like devised, organized, supervised, improved, created, and developed. Make it look beautiful by avoiding spelling mistakes, typos, .. That is, very careful proofreading.

Designing Letter of Application

Usually one page long with four main sections:
The heading: includes writer's and reader's addresses and date. A first paragraph that:

Introduces you (with an impressive reference). Establishes the company's need and your ability to fill it, or, Establishes the reason for writing and your request from the reader.

Designing Letter of Application (Contd.)

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

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 (Contd.)

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.

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

Business Letters (Contd.)

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 (Contd.)

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

Basic Letter Formats

Three basic formats: The Unblocked Format The Semiblocked Format The Blocked Format (See the models provided)

III. Reports Basic Features

Generally, reports are read by mixed audiences and thus should be accessible to them and responsive to their needs. The responsiveness may be increased by two structural features of a report, The Argumentative Structure, which is appropriate for managers (they see the info they need up front). The two features are

The Argumentative Structure

The Foreword and Summary (or counterparts): at the beginning for managerial 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

To catch the reader's attention: Why the report was done and why it is important. To quickly orient the audience to the subject of the report (what was done). To define the purpose or focus of the report (predict what info the report will present).

Foreword (Contd.)
An effective foreword (problem setup) provides the driving force and overall organizational structure of the report.

The Argumentative Structure

(Contd.)
The Summary provides 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.

The Argumentative Structure

(Contd.)
Technical Discussions (details) for specialist readers followed by Appendixes of nonessential or lengthy details.

Report Structures
The Narrative (Chronological) Structure: found in lab and research reports and journal articles. Presents info in the chronological order it occurred.