Saleh Fareed

University of Petra
Faculty of Information Technology

Dr. techn. Dipl. Inform. Bassam Haddad

Associate Professor of Computer Science
Faculty of Information Technology
University of Petra

Technical Writing

An Introduction
Part I
Course No.: 601201
Prerequisite: 402102

Based on:
The Mayfield Handbook of Technical and Science Writing
Leslie C. Perelman, James Paradis Edward Parrett,
Mayfield Publishing Company, Inc.
Technical Report Writing Today
Pauley, Riordan, Houghton Miffin Company USA, 1998
The Craft of Scientific Writing, 3rd edition
(Springer-Verlag, 1996

2007/2008 Dr B. Haddad
Faculty of Information Technology
1
University of Petra
 Saleh Fareed

Technical Writing
Covering
Introduction to Technical Writing
-Definition of Technical Writing
-Characteristics of Effective Technical Communication
-Accuracy, Clarity, Conciseness, Coherence, Appropriateness
Planning and Producing Documents
-Document Purpose, Problem Statement, Audience
-Technical writing process
Document Types
-Memoranda
-Literature Reviews
-Reports, Research Reports
-Research Articles, Progress Reports
-Letters, References and Letters of Recommendation
-Technical-Information Letters and Memoranda
Software Documentation and Source code comments
-Writing Software Documentation
-Tools for software documentation
-Examples
Proposals
Task-Oriented Documents
-Specifications, Documentation (Manuals), Technical Documentation
Theses
-The Thesis-Writing Process, Thesis Proposal, Format of the Thesis, Thesis
Oral Presentations
-A Design Review
Elements of Technical Documents
-Sections and Subsections, Headings and Subheadings
-Front Matter,
-Body
-End matter
Graphs and Figures
-Common Graphics, Tables, Bar Graphs, Illustration, Diagrams, Photographs
Schematic-Graphs, Flowcharts, Timetables
Paragraphs
Sentence
Words
-Technical terms, Vague language, biased language
Punctuation
Citing and Listing Reference
Part of Speech
Writer's Resources
Introduction to Scientific Word and LaTeX, review PowerPoint, MS-word !!
Common Writing Problems for Non-Native Speakers of English

2007/2008 Dr B. Haddad
Faculty of Information Technology
2
University of Petra
 Technical Writing
Saleh Fareed

The principle goal

Providing the students with techniques necessary for

developing essential writing and communication skills.
through a broad approach based on
-planning
-researching,
-writing
-completing, and
-presenting acquired knowledge

Why to learn SD and TW

I. Information about a computer system or piece of software

or any technical field is distributed amongst a number of
information sources, including the interface, the user, other
people and especially

paper and on-line documentation.

II. Communication skill for Computer Scientists

Scientists and engineers are called upon

to communicate in many different situations:
- Reports, Article, Proposals, Web Pages
- Conferences, Lectures, Meetings, Posters

2007/2008 Dr B. Haddad
Faculty of Information Technology
3
University of Petra
 Saleh Fareed

Technical Writing: Definition?

TW is difficult to define. However there is

Adopted from Tech. Report Today

A. TW as an operational Definition (Job of some people)

(executive Manager, Research scientist, secretary
people who generate documents of different types such as
Memos, letter, research and progress report, students, Prof., )

B. Purpose of Technical Writing

to inform to instruct to persuade

Ex. Challenger explosion

2007/2008 Dr B. Haddad
Faculty of Information Technology
4
University of Petra
 Saleh Fareed

Technical Writing: Definition and why?

How well you communicate affects your career

Survey:
Successful engineers spent 25% of
work week writing
by Richard M. Davis of the Air Force
who surveyed 245 distinguished
engineers.

Survey (Wisconsin)
Professional engineers found writing
their most useful subject in college
By Dean John Bollinger from the College of
Engineering at the University of Wisconsin who
contacted 9000 engineers who had graduated.

Survey (Virginia Tech)

Recruiters claim that engineers need more
work on their writing

2007/2008 Dr B. Haddad
Faculty of Information Technology
5
University of Petra
 Saleh Fareed

Technical Writing: Definition and why?

How well you communicate affects the well-being of others

communication problems

Space Shuttle Challenger

(January 28, 1986)

Explosion was caused by failure of O-rings in the

solid rocket boosters
Engineers knew of O-ring problems well before fatal
launch
Engineers failed to communicate seriousness of
problem
From the craft of scientific writing
Springer verlag

2007/2008 Dr B. Haddad
Faculty of Information Technology
6
University of Petra
 Saleh Fareed

Technical Writing Process

The goal is to generate a clear, effective document for
Audience

Activities:
Prewriting: Planning
Writing: drafting and revising
Postwriting: finalizing
Writing

Prewriting Post-Writing

Plan
Determine the Finalize
Audience (who they Draft Edit for
are) Apply strategy to Consistency and
Goal (what is the Style, Organization accuracy
basic massage?) and Interest
Constraints Understand your
Basic fact Apply strat. To help Method of producing
yourself brainstorm the doc
Tentatively (go back to your Dont finish very soon
establish str.) (reviewer)
Strategy Revise to help
Tone readers
Outline comprehension
Page format and
visual supports
Production schedule

Adopted from Tech. Report Today

2007/2008 Dr B. Haddad
Faculty of Information Technology
7
University of Petra
 Saleh Fareed
Characteristics of Effective Technical Communication

Five characteristics
-Accuracy, Clarity, Conciseness, Coherence,
and appropriateness

Good technical communication is

Accurate
-accurate document needs to focus
clearly on a problem
Clear
- refers to ease of understanding
-anyway clarity is a special problem in science
and technology writing)
Concise
-The concise document is a piece of writing that
conveys only the needed material
Coherent
-Coherence is the quality of hanging together
and of providing the reader an easily followed
path.
Appropriate
-the document has to be appropriate to the goals
in writing it
-audience's purpose in reading it
-the specific institutional contexts in which it is
written and read.

These qualities are sometimes difficult to achieve.

Not only do science and technology depend heavily
on specialized concepts and terminologies, but they
also make extensive use of numbers and graphics.

2007/2008 Dr B. Haddad
Faculty of Information Technology
8
University of Petra
 Saleh Fareed
Planning and Producing Documents
Planning

I. First, establish basic criteria.

-Such as Accuracy, Clarity, Conciseness, Coherence, appropriateness

II. Identify the specific purpose of the doc.

-Why are you writing, The Reasons for writing?
-Determine the Objectives

iii. Focus on the Statement of the Problem

-Vague problem definition leads to unsuccessful proposals
- Naming a topic is not the same as defining a problem. (s. exam.)

IV. Determine Doc. General Type (Memoranda, Literature

Reviews, Reports, Research Reports, Research Articles,
Progress Reports ,Technical-Information Letters

V. Define your audience

-Then determine your audience's level of expertise
(experts, technicians, managers , laypersons)
-Attitude to you. It is also important to assess the of the audience
toward both you . (are you expert in his view, or he doesnt know you

VII. Sketch out a preliminary outline to organize it.

-Keeping purpose and audience in mind.
-Sketch out graphics and tables to display your important data.

viii. Write a first draft. At this point in the

process, do not be overly concerned about grammar,
style, or usage. (Using your outline and preliminary graphics)

ix. Finally, edit your paragraphs and sentences to improve their

clarity, conciseness, and coherence, and to fix any problems in
grammar, spelling, punctuation, mechanics, or usage.

x. Reviews. The last major step for most technical documents is one
or more Reviews
2007/2008 Dr B. Haddad
Faculty of Information Technology
9
University of Petra
 Saleh Fareed
Planning and Producing Documents

II. Type of possible Document purpose

Purpose

Explicit Purpose Implicit Purpose

Explicit Purpose (Goal)

-to provide information
-to give instructions
-to persuade the reader
-to enact (or prohibit something)

- Explicit Purpose should sometimes stressed by a

formal statement of objective (s. ex.)

Implicit Purpose (Goal)

a-To Establish a Relationship

(well-written letter can begin a relationship)

b-To Create Trust and Establish Credibility

(accurate TW helps to create trust and competence)

c-To document Actions

(Scientists, engineers, and managers

often use writing to create permanent records of their thoughts
and actions)

2007/2008 Dr B. Haddad
Faculty of Information Technology
10
University of Petra
 Saleh Fareed
Planning and Producing Documents

II. Purpose explicit: Examples (explicit Goals)

To provide information

( This document will discuss the theoretical basis of Semantic

Representation of Arabic. )

To give instructions

(This document outlines a procedure and the steps how to

construct logical formulas for Arabic Sentences

To persuade the reader

(This document proposes a novel method for compositional

semantic of Arabic)

To enact (or prohibit) something

(NOTICE: Semantic Composition cannot be applied for the whole

Language)

2007/2008 Dr B. Haddad
Faculty of Information Technology
11
University of Petra
 Saleh Fareed
Planning and Producing Documents

II. Purpose explicit: Examples (explicit Goals)

Notice

I. Make the explicit purpose clear at the beginning of your

document in an

- abstract
- an executive summary
- an introduction, or all of these.

II. Make a formal statement of objective if necessary

III. keep in mind important implicit goals in mind.

Among the most common of these goals are to
establish

- a relationship,
- to create trust and credibility, and
- to document actions.

Example for statement of Objective

The following opening sentence from a memorandum by an engineer at Morton
Thiokol warning his superiors of the problem that later caused the explosion of
the space shuttle Challenger provides an example of a good statement of
objective.

This letter is written to ensure that management is fully aware

of the seriousness of the current O-Ring erosion problem in
the SRM joints from an engineering standpoint.

--R. M. Boisjoly

2007/2008 Dr B. Haddad
Faculty of Information Technology
12
University of Petra
Memo from Roger Boisjoly on O-Ring Erosion Saleh Fareed

Morton Thiokol, Inc

Wasatch Division

Interoffice Memo
31 July 1985
2870:FY86:073

TO: R. K. Lund
Vice President, Engineering

CC: B. C. Brinton, A. J. McDonald, L. H. Sayer, J. R. Kapp

FROM: R. M. Boisjoly
Applied Mechanics - Ext. 3525

SUBJECT: SRM O-Ring Erosion/Potential Failure Criticality

This letter is written to insure that management is fully aware of the seriousness
of the current O-ring erosion problem in the SRM joints from an engineering standpoint.

The mistakenly accepted position on the joint problem was to fly without fear of failure
and to run a series of design evaluations which would ultimately lead to a solution or at least
a significant reduction of the erosion problem.
This position is now drastically changed as a result of the SRM 16A nozzle joint erosion
which eroded a secondary O-ring with the primary O-ring never sealing.

If the same scenario should occur in a field joint (and it could), then it is a jump ball as to the
success or failure of the joint because the secondary O-ring cannot respond to the clevis
opening rate and may not be capable of pressurization. The result would be a catastrophe of th
highest order - loss of human life.

An unofficial team (a memo defining the team and its purpose was never published) with
leader was formed on 19 July 1985 and was tasked with solving the problem for both
the short and long term. This unofficial team is essentially nonexistent at this time.
In my opinion, the team must be officially given the responsibility and the authority to
execute the work that needs to be done on a non-interference basis
(full time assignment until completed.)

It is my honest and very real fear that if we do not take immediate action to dedicate
a team to solve the problem with the field joint having the number one priority, then
we stand in jeopardy of losing a flight along with
all the launch pad facilities.

R. M. Boisjoly
Concurred by:
J. R. Kapp, Manager
Applied Mechanics

2007/2008 Dr B. Haddad
Faculty of Information Technology
13
University of Petra
 Saleh Fareed
Problem Statement

III. Problem Statement

A) If you are focusing on a problem, be sure to define and state it

specifically enough that you can write about it.
B) Avoid trying to investigate or write about multiple problems or
about broad or overly ambitious problems.

Vague problem definition leads to unsuccessful proposals and vague,

unmanageable documents. Naming a topic is not the same as defining a
problem

Examples for stating a Problem Statement

Weak
Morpho-Probabilistic Arabic Analyzer

[This definition is too vague; it suggests a broad topic but not an

approach to the topic.]

Improved
Morphological Arabic Analyzer based statistical Analysis
of root with possible patterns: Morpho-Probabilistic
Arabic Analyzer
[Haddad &Yaseen]

Weak
Engine starting and warm-up behavior.

Improved
Effects of fuel enrichment on engine starting and warm-
up behavior.

2007/2008 Dr B. Haddad
Faculty of Information Technology
14
University of Petra
 Saleh Fareed
Problem Statement

Problem Statement Elements

Problem itself solving method purpose

statement of objective
scope

Problem statements often have three elements:

I. the problem itself stated clearly and with enough

contextual detail to establish why it is important
II. the method of solving the problem, often stated
as a claim or a working thesis
III. the purpose, statement of objective and scope of
the document the writer is preparing.

(These elements should be brief so that the reader

does not get lost. )

2007/2008 Dr B. Haddad
Faculty of Information Technology
15
University of Petra
 Saleh Fareed
Problem Statement

Examples

[problem and its context]

Semantic processing of human languages is a problematic issue of
natural language processing. Artificial Intelligence had a long time
ago recognized the importance of semantic representation in context
of performing some semantic inferences to achieve human language
understanding. Unfortunately, despite the significance of this issue,
semantic processing based on logical models in the case of Arabic has
so far received very little research attention.
One of the main factors for this negligence might reside in the
complexity of this field and, in the invisible collaboration between
scientists working in the filed of Artificial Intelligence, Arabic, Logic
and Linguistics. Therefore, there is a critical need to design
sufficient models for semantic processing of Arabic.

[approach of the current research

The key idea underlying compositional approaches is that the
meaning of a sentence can be composed from the meaning of its
syntactical constituents. The semantic representation of an Arabic
syntactic phrase should be a logical function of its constituent words
and phrases. Each word and well-formed syntactic Arabic phrase
should be represented by a semantic function.

[purpose and scope of current document]

This work will focus the attention on the fundamentals involved in the
compositionality of Arabic elementary syntactical constituents and
their Meaning as a departure point towards developing a potential
comprehensive computational semantic for Arabic.
International Journal of Computer Processing of Oriental Languages (IJCPOL)
Volum2 20, Number 1, March 2007
Semantic Representation of Arabic: A Logical Approach towards Compositionality and
Generalized Arabic Quantifiers
B.H.

2007/2008 Dr B. Haddad
Faculty of Information Technology
16
University of Petra
 Saleh Fareed
Audience

V. Audience

Audience considerations

1. Audience type and level of expert

2. Audience's purpose in using the document
3. Audience's attitude

influence features of the doc

Organization
Introductions
Equations and mathematical models
Graphics
Technical terms and
Level of detail.

2007/2008 Dr B. Haddad
Faculty of Information Technology
17
University of Petra
 Saleh Fareed
Audience

Audience type and level of expert

Expert Technician Manager Layperson

Mixed Audience

organization of the doc (outlines and draft)

density of information

Variation to meet

your audience's purpose in reading the document

their level of expertise.

Organization is the arrangement of elements into a structure

(see Process later)
-Work strategy
-Outline
-Making document coherent to your audience

2007/2008 Dr B. Haddad
Faculty of Information Technology
18
University of Petra
 Saleh Fareed
Audience

Audience type and level of expert

Experts
- General experts or specific experts

Technician
- They are also usually familiar with the common technical
terms associated with the devices they use and the
processes they perform. They may not be familiar, however,
with general or Abstract

Manager
-Assume that managers are busy people who need to use
documents primarily as tools in making decisions. Because
managers read and review many documents, be brief and to
the point. Managers usually supervise a number of projects, so
they may not be familiar with every recent technological
advance. And often managers are specialists in fields such
as marketing or management and have little detailed technical
knowledge. See Doc. Density)

Laypersons
(All of us read some documents as laypersons; no one is an
expert in all fields.)

Mixed Audience
Computer documentation, may be written for experts who are
familiar with all the hardware and software processes involved
Technicians: who will install and support the application,
A Manager: who may be deciding whether or not to purchase
the software,
Laypersons who may occasionally use it.

2007/2008 Dr B. Haddad
Faculty of Information Technology
19
University of Petra
 Saleh Fareed
Audience

2 . Audience's purpose in using the document

Readers of technical and scientific writing read a
document for three general purposes:

Audience's purpose

to learn how to do something

to acquire information

to help make decisions

2007/2008 Dr B. Haddad
Faculty of Information Technology
20
University of Petra
 Saleh Fareed
Audience

2. Audience's purpose

a) to acquire information
Experts: to maintain their level of expertise and read documents
in related fields to increase the breadth of their knowledge

Technicians and Experts: to acquire a basic understanding of

general concepts and processes that will help them perform
their tasks and diagnose and solve problems they may encounter

(note: experts or technicians in one field are often

novices in another field)

Managers: to acquire both the general and the specific information

necessary for them to supervise their staffs effectively
and to function well in their organizations.

Laypersons: to acquire general knowledge about a subject or as

novices attempting to become experts.

b) to help make decisions

Expert: to decide whether or not to conduct
a specific experiment or to use a new design element.

Manager: may need to make or approve a decision.

Technicians: use documents to decide on the selection
of specific hardware and software and to determine
the best procedure for performing a task.
Laypersons may read documents to help select a particular
product or investment.
c) to learn how to do something
All readers read instructions to help them perform various tasks.
E.g. manager may read a document to learn how to use new
budgeting software.
2007/2008 Dr B. Haddad
Faculty of Information Technology
21
University of Petra
 Saleh Fareed
Audience

3 . Audience's attitude

a) to you and your Organization

b) Audience Interest in Subject
c) Audience Attitude Toward Subject

a) Attitude Toward You and Your Organization

your audience views you as an expert

not need to offer lengthy explanations for your

conclusions and recommendations.

( we do not always ask an expert doctor for a detailed

explanation of a diagnosis or procedure).

Audience does not know you, or has had past negative

experience with you or your organization

Extensive Details

2007/2008 Dr B. Haddad
Faculty of Information Technology
22
University of Petra
 Saleh Fareed
Audience

b) Audience Interest in Subject

your audience is already interested in your subject, you

shorten your introduction.

your audience is not interested in your subject or

you do not know the level of their interest

explain why the material in the document

is important to the reader.

2007/2008 Dr B. Haddad
Faculty of Information Technology
23
University of Petra
 Saleh Fareed
Audience

c) Audience Attitude Toward Subject

The audience initially may be hostile to your

major conclusions

present the
1) problem first
2) then your analysis
3) then your conclusions or recommendations.

The audience to be receptive to your conclusions

(especially if your audience is a manager)

begin with conclusions and recommendations

2007/2008 Dr B. Haddad
Faculty of Information Technology
24
University of Petra
 Saleh Fareed
Audience

Document Density an Audience

Document density refers to the

Amount,
Type
Detail,
Complexity,
Rate of information
presented to the reader.

2007/2008 Dr B. Haddad
Faculty of Information Technology
25
University of Petra
 Saleh Fareed
Audience

Document Density and Audience

The following table presents some general guidelines for

Document Density

Feature of
Expert Managerial Layperson
Document

Problem/soluti
Introductions Technical Relevance
on
Math models OK Avoid Avoid
Keep simple or
Equations OK Avoid
avoid
Detailed, Simple, General
Graphics
analytical presentational illustrative
Accurate, General, Simple,
Detail level
numerical accurate narrative
Technical Expert, General,
Administrative
terms technical illustrative
Operations, Informational,
Emphasis Analysis
costs interest

2007/2008 Dr B. Haddad
Faculty of Information Technology
26
University of Petra
 Saleh Fareed
Examples

Warnings
Terfenadine undergoes extensive metabolism in the liver
by a specific cytochrome P-450 isoenzyme.
This metabolic pathway may be impaired in patients with
hepatic dysfunction (alcoholic cirrhosis, hepatitis)
or who are taking drugs such as ketoconazole,
itraconazole, or clarithromycin, erythromycin, or
troleandomycin (macrolide antibiotics), or other potent
inhibitors of this isoenzyme. Interference with this
metabolism can lead to elevated terfenadine plasma
levels associated with QT prolongation and increased
risk of ventricular tachyarrhythmias (such as torsades
de pointes, ventricular tachycardia, and ventricular
fibrillation) at the recommended dose. SELDANETM is
contraindicated for patients with these conditions
(see WARNING BOX, CONTRAINDICATIONS, and
PRECAUTIONS: Drug Interactions)

--Physicians' Desk Reference

Because the foregoing document is written for experts who will be using the
information for what may be life-or-death decisions, the information
provided is extensive.
The document describes in detail the biological processes that make the
drug dangerous to patients with liver problems and lists the two specific liver
diseases that should deter doctors from prescribing the drug. Similarly, the
passage gives an exhaustive list of all drugs that might cause specific heart
problems.
Because the document is intended for experts familiar with medical jargon,
technical terms such as isoenzyme and ventricular tachycardia are used
without any explanation.
2007/2008 Dr B. Haddad
Faculty of Information Technology
27
University of Petra
 Saleh Fareed

Example

As an example of a language rule that is difficult to

specify with BNF, consider type compatibility rules. In
Java, for example, a floating-point value cannot be
assigned to an integer type variable , although the
opposite is legal. Although this restriction can be
specified in BNF, it required additional non-terminals
symbol and rules. If all of the typing rules of Java were
specified in BN, the grammar would be become too
large to be useful because the size of the grammar the
size of the parser

Static Semantic, (130, Attribute Grammar, concept of Prog.

Lngauges , R. Sebesta,203)
Terms
language rule
BNF
floating-point value
non-terminals
Parser
grammar

2007/2008 Dr B. Haddad
Faculty of Information Technology
28
University of Petra
 Saleh Fareed

2007/2008 Dr B. Haddad
Faculty of Information Technology
29
University of Petra
 Saleh Fareed

University of Petra
Faculty of Information Technology

Dr. techn. Dipl. Inform. Bassam Haddad

Associate Professor of Computer Science
Faculty of Information Technology
University of Petra

Technical Writing
Organization and Documents
Types
Part II
Course No.: 601201
Prerequisite: 402102

Based on:
The Mayfield Handbook of Technical and Science Writing
Leslie C. Perelman, James Paradis Edward Parrett,
Mayfield Publishing Company, Inc.
Technical Report Writing Today
Pauley, Riordan, Houghton Miffin Company USA, 1998

2007/2008 Dr B. Haddad
Faculty of Information Technology
1
University of Petra
 Saleh Fareed

VI. Sketching Doc Organization and outlines

Doc Organization

Organization is the arrangement of elements into

structure

Doc Organization
is ensuring is

Work strategy for Coherence of Document planning

setting priorities Introductory Develop Outline for
Use Work plans as Body General Structure
Aids for producing Conclusion and Section
A schedule (in
Proposals,
Progress reports

We will discuss Work plan later in Elements of Technical Documents

2007/2008 Dr B. Haddad
Faculty of Information Technology
2
University of Petra
 Saleh Fareed

VI. Sketching Doc Organization and outlines

Developing a Detailed Outline

reduce effectively and order your source materials

will help in

Partition material
Developing a point of view
Establishing the scope of the
document
Sequence your topics
Developing a writing strategy
Providing the subject headings of
your paper
Utilized in generating feedback

Recommendations

Work out a general plan first, and then

Make the outline more specific.
(See Example)

2007/2008 Dr B. Haddad
Faculty of Information Technology
3
University of Petra
 Saleh Fareed

VI. Sketching Doc Organization and outlines

Developing a Detailed Outline: An Example

Title: "Chemical Changes in Ground Water Preceding the Kobe

Earthquake"

General Specific
Problem Description of quake
Background Prediction model (Approach)
Method Ground water variables, flow rate, radon
Results Flow rate
Before quake
After quake

Radon content
Before quake
After quake

Analysis Comparison with other recent quakes

Possible mechanisms of change
Fissure widening from regional tectonic stress
Permeability from increased microcracking

--H. Wakita and U. Tsunogai, "Precursory Chemical Changes in Ground Water,

Kobe Earthquake," Science

2007/2008 Dr B. Haddad
Faculty of Information Technology
4
University of Petra
 Saleh Fareed

VI. Sketching Doc Organization and outlines

Developing a Detailed Outline: An Example

Specific
General

Problem Semantic Representation of Arabic

Background Logical model, Predicate Logic first order

Method Syntactical Analysis, Lambda Calculus

Results Logical formulas for
Arabic Nominal Sentence
Arabic Quantifier
Simple Arabic Sentence
Analysis Comparison with other Semantic Analyzer
Arabic exhibits compositional character like
Latin based Languages

Example: Composition Semantic of Arabic Project , Haddad

2007/2008 Dr B. Haddad
Faculty of Information Technology
5
University of Petra
 Saleh Fareed

VI. Sketching Doc Organization and outlines

Informal Outline
sometimes called a scratch outline, the writer brainstorms
to develop a list of topics, which are then put into some
order

Example:
Title: Arabic Non-Word Detection and Correction: A Morpho-
Probabilistic Approach

Introduction: Covering Arabic morphological Analyzer and

Spell Checkers
Root-pattern in Arabic
3-radical Arabic Roots
Root-Pattern relatiionship
Statistical measure to predict root given pattern
Examples:
P(root/pattern)=P(rootPattern)/ P(pattern)

P( / > ) P( / )
P( / >) 0

2007/2008 Dr B. Haddad
Faculty of Information Technology
6
University of Petra
 Saleh Fareed

VI. Sketching Doc Organization and outlines

Formal Outline

Developing a numbering system to accompany the

topics (developing a writing strategy)
The process of creating and sequencing the topics is a
critical stage in developing your document, because the
resulting plan determines the document's internal logic and
order. In the following outline, the writer
The outline will help the reviewer and reader understand
the writer's goals

Outline: Tools and Materials for High-Speed Machining: A Survey

1 Progress in tool technology is largely speed-based

1.1 Materials
1.2 Automation
2 Tool failure mechanisms
2.1 Fracture
2.2 Deformation
2.3 Wear
3 Strategies for developing tooling systems for high-speed machining
3.1 Chemically stable materials
3.2 Diffusion-limited wear regimes
3.3 Isolation of the tool from the workplace
4 Conclusions
4.1 Aluminum alloys
4.2 Hard steels
4.3 Titanium alloys

2007/2008 Dr B. Haddad
Faculty of Information Technology
7
University of Petra
 Saleh Fareed

VI. Sketching Doc Organization and outlines

Subject Headings

Headings to help guide the reader through the

document.
Headings must be identical with your table of contents.
Many word processors can automatically generate a
table of contents from your subject headings.

Example:
Interests in AI appeared in the mid-1950 in a number of places.
Some of this interests grew out of linguistics, some from
psychology, and some from mathematics. Linguistics were
concerned with Natural Language Processing. Psychologists were
Interested in modeling human information storage and retrieval, Along
with other fundamental process of brain. Mathematicians were
interested in mechanizing certain intelligent process, such as
theorem proving. All of these investigation arrived at the same
conclusion: some method must be developed to allow computer to
process symbolic data in linked list. At the time, most commutation
was on numeric data in arrays.
LISP was the first functional Programming Language was invented to
provide language features for list processing, the need for which grew
out of the first application in the area of Artificial Intelligence. Pure
LISP has only two kinds of data structures: atoms and lists. Atoms are
..

Concept of Programming Languages, R. Sebesta2003

2007/2008 Dr B. Haddad
Faculty of Information Technology
8
University of Petra
 Saleh Fareed

Better

Interests in AI appeared in the mid-1950 in a number of places.

Some of this interests grew out of linguistics, some from
psychology, and some from mathematics. Linguistics were
concerned with Natural Language Processing. Psychologists
were Interested in modeling human information storage and
retrieval, Along with other fundamental process of brain.
Mathematicians were interested in mechanizing certain
intelligent process, such as theorem proving. All of these
investigation arrived at the same conclusion: some method
must be developed to allow computer to process symbolic data
in linked list. At the time, most commutation was on numeric
data in arrays.

Functional Languages: LISP

LISP was the first functional Programming Language was
invented to provide language features for list processing, the
need for which grew out of the first application in the area of
Artificial Intelligence. Pure LISP has only two kinds of data
structures: atoms and lists. Atoms are ..

New :Subject Headings

2007/2008 Dr B. Haddad
Faculty of Information Technology
9
University of Petra
 Saleh Fareed

Forecasting

Forecasting
Presenting the whole before the parts. (Giving general
Overview and outlook of where you are going before you
plunge into the details)
One of the common problems in reading science and
engineering materials is that of trying to understand the
context of the discussion.
This principle applies to the
-introductions of documents, as well as to the
- openings of document sections. S. Coherence
Example
In this paper we are trying to discuss how to represent causal
relationships between clinical categories such as clinical
observations; i.e. findings or symptoms, pathophysiological states,
diagnosis or diseases, tests and therapies. Relationships can be
represented in different ways and at different levels. However, as
most medical knowledge is uncertain and or imprecise, representing
medical knowledge requires methods capable of dealing with
uncertainty and imprecision such as interval. On the other hand,
obtaining pure statistical precise values for representing uncertain or
imprecise relationships might be very complex to acquire. Even
quantitative medical information coming from measurement are
never 100% accurate, they are usually expressed in term of interval
considering the measurement error factor.
Better
This paper addresses central issues involved in representing
uncertain causal relationships between entities in medical
knowledge. An interval-based approach for medical binary fuzzy
relations is proposed to represent the ignorance about uncertain
relationships.

2007/2008 Dr B. Haddad
Haddad Faculty of Information Technology
10
University of Petra
 Saleh Fareed

VII. Drafting a Technical Document

After collecting
1) information, identifying document's
2) purposes
3)objective (statement of Objective)
4) audience
5) developed an appropriate outline, and, if
appropriate
6) sketched out key graphics and tables,

write the first draft

Some Remarks

Writing can generate new ideas. If you discover potentially

relevant new ideas or approaches, include them even if they are
not in your outline. You can revise your outline when you edit for
organization.

The main goal of a first draft is to organize ideas in writing. But,

fixing specific problems in sentences, words, grammar, and
spelling could hinder the development of important and interesting
ideas. Many writers just mark these problems when writing a first
draft and then address them when they
(edit for grammar, style, see later)
You may find yourself needing to locate or develop additional
data or to confirm already existing data. Make Marginal notes or
comments in the text (e.g., "add median response time," "need
figures," or "check maximum values") allow you to keep your ideas
flowing.

You do not need to write the document in the order of your

outline. You can write the introduction and the conclusion of a
document last.
2007/2008 Dr B. Haddad
Faculty of Information Technology
11
University of Petra
 Saleh Fareed

Revising Organization

Revise your document to produce a predictable and

logical structure between and within sections.
Overall document coherence: A predictable and logical
structure of the doc, which allows your audience to read
the document efficiently and to use its information
effectively.
The first review of any technical document should focus
on Coherence; i.e. ensuring a logical and accessible
structure.

Reviewing Organization

1) Divide your document into sections and subsections by inserting

headings and subheadings into your document. (if not already done)
2) Review table of contents
3) Are all the elements of your document type present and in
the appropriate order? If not
are there good reasons for omitting or rearranging some sections?
4) Does each section and subsection follow
logically from the preceding one?
5) is there a clear road map of the entire document (Review Forecasting)
6) Review the graphics in the order presented in your document.
Do they present the key information to the reader in a logical order?

7) Read aloud the topic sentence of each paragraph of your document.

Do ideas flow smoothly from paragraph to paragraph?
Will the relationship between one idea and the next be clear
to your audience

2007/2008 Dr B. Haddad
Faculty of Information Technology
12
University of Petra
 Saleh Fareed

Revising Organization

Strategies for Revising Organization

If appropriate, add sections, subsections, and section headings, and

subheadings to make your document conform to its standard type.
If appropriate, add sections and subsections to improve the logical
structure and coherence of your document.
If necessary, revise the forecasting statements to provide the reader
with an accurate road map of the ideas that will follow.
If appropriate, add new graphics and revise and rearrange old ones
to provide the reader with a visual summary of the document's central
ideas.

2007/2008 Dr B. Haddad
Faculty of Information Technology
13
University of Petra
 Saleh Fareed

Revising Content

After reviewing the organization of your document

Revising content: ensure that all information is

1) accurate
2) complete, and comprehensible.
3) is the information relevant to your document's
purpose and to your audience's use.
Questions About Content

Read through your draft slowly, stopping at the end of each section,
and ask yourself the following questions:

1) Is the information accurate?

a) Are there any incorrect data entries?

b) Are all outside sources documented?
Is all information from outside sources either paraphrased or
quoted exactly and enclosed in quotation marks?
c) Are any graphics misleading?
d) check up all table and graphics

2) Is the information complete?

- Have you omitted any facts, concepts, equations or processes
necessary for the document's aim and for the audience type and
the audience's purpose?

a) Is all quantitative information presented fully?

b) Are all concepts explained in the detail appropriate for the

document's aim and for the audience type and the audience's
purpose?
c) Are there any steps missing from instructions, procedures, or
descriptions of processes?
d) Is any irrelevant information included in the document?

2007/2008 Dr B. Haddad
Faculty of Information Technology
14
University of Petra
 Saleh Fareed

Revising Content

Questions About Content

3) Is any irrelevant information included in the document?

4) Is the information comprehensible to your audience?

a) Are all technical terms that need to be defined for your audience clearly
defined?
b) Are all technical terms used correctly?
c) Are all technical terms used consistently?
d) Do you always use the same term to refer to something?
e) Are all acronyms explained when first used?
f) Is the density of information appropriate to the expertise and purpose
your audience?

Strategies for Revising Content

Correct any inaccurate quantitative data or other information.

Add further information, explanations of concepts and processes, and
instructions necessary for your document's aim and audience.
Delete from the body of the document any information that is unessential and
unimportant to most of your readers. If the information will be important to some
of your readers, include it in one or more appendixes.
Clarify technical terms.
a) Replace any term that is used incorrectly.
b) Replace any vague terms.
c) If a single term is used to refer to two or more separate items, replace the
term with separate terms for each item.
d) If two or more terms are used to refer to a single item, choose the best
term and replace all occurrences of the other terms with the one you have
selected.
e) The first time you use an acronym or an abbreviation that may not be
familiar to all your readers, write out the complete term followed by the
acronym or abbreviation in parentheses.
f) Consider adding a glossary if you use many terms with which some
readers may not be familiar.
Separate important technical terms and concepts so that your audience may
easily digest the material.

2007/2008 Dr B. Haddad
Faculty of Information Technology
15
University of Petra
 Saleh Fareed

VIII. Editing for Grammar and Style

Continue doing Refinement and review on the Text, sentence, word and
Punctuation level: improve accuracy, clarity, conciseness , coherence and
appropriateness.
E.g. could any sentences be made more effective by restructuring?

Important remake

No matter how sound your document may be technically, your

credibility will be damaged and undermined by errors in
- Sentence Construction or Grammar
- Word choice, usage
- Punctuation, mechanics
- Spelling

What to do?

If you need more information about grammatical elements, refer to

parts of sentences
parts of speech.

If English is not your native language, check the list of common

ESL writing problems.
(Common Writing Problems for Non-Native Speakers of English,
see reference )

Finally If your document is supposed to follow an established style

for citing sources and creating a reference list, have you followed the
right style correctly and consistently?

2007/2008 Dr B. Haddad
Faculty of Information Technology
16
University of Petra
 Saleh Fareed

VIII. Editing for Grammar and Style

complex sentence
When you come to sentences that are hard to follow,
- locate the main agent (thing doing something) and the
- action (thing being done):

1. Circle the main subject or agent of the sentence. This noun will
identify the who or what of the sentence.

2.Circle the main action word. This verb is the key to the action
(thing being done or state of being) of the sentence.
3.Whenever possible, organize the sentence around the subject and
verb. Make the agent the subject and the action the main verb of the
sentence.
(Head Driven Phrase Grammar)

Weak
The solid was contaminated [main action] as a result of a leaking
cleaning solution [main agent].

Improved
A leaking cleaning solution contaminated the solid.

2007/2008 Dr B. Haddad
Faculty of Information Technology
17
University of Petra
 Saleh Fareed

Some Recommendations to tighten up your prose

Make your paragraphs coherent. If necessary, rearrange

sentences for better paragraph flow and logic.
Use the active voice whenever the passive voice is not clearly
more appropriate.
Eliminate unnecessary words and phrases.
Simplify your sentences. Break long sentences into manageable
units.
Condense repetitious or closely related material. Look for ways
to combine or delete words and sentences that repeat
information.
Be specific. Replace vague phrases and words with more
descriptive ones.
Use words accurately. Look for phrases and words that don't
stand up to scrutiny

2007/2008 Dr B. Haddad
Faculty of Information Technology
18
University of Petra
 Saleh Fareed

Reviewing a Document

After doc have been

Written
Revised and
edited
almost all technical documents undergo one or more reviews
Common Types of reviewers

Peer reviews by colleagues

- The most useful step in the review process. colleagues are often closer to
the project.
-Peer reviews are often less formal and less threatening than managerial or
technical reviews.
Technical reviews by experts
-rewiring technical accuracy (a doc with wrong content is a west of
time)
- Technical review is concerned with one or more of the following questions
a) is the problem technically impotent
b) Does the doc solve the problem it sets out to solve
c) are the methodology technically sound
d) new conclusion and new question in the research
Editorial reviews by colleagues or editors
-Editorial reviews aim to improve the readability of a manuscript.
Managerial reviews by supervisors
-often stressful since staff and management perspectives are predictably
different (conflict
s. table you might understand your examiner

2007/2008 Dr B. Haddad
Faculty of Information Technology
19
University of Petra
 Saleh Fareed

The following list highlights some typical conflicts during the review
process.

Writer's Perspective Supervisor's Perspective

1. I want to show what I've 1. This document needs to advance the
been doing. organization's objectives.
2. He won't tell me what he
2. He throws rough drafts at me.
wants.
3. I don't understand her
3. It takes three or four reviews.
criticisms.
4. He tries to put it in his
4. I have to fix a lot of bad prose.
style.
5. I spend too much time
5. She doesn't spend enough time writing.
writing.

--J. Paradis, D. Dobrin, R. Miller, "Writing at Exxon ITD"

2007/2008 Dr B. Haddad
Faculty of Information Technology
20
University of Petra
 Saleh Fareed

University of Petra
Faculty of Information Technology

Dr. techn. Dipl. Inform. Bassam Haddad

Associate Professor of Computer Science
Faculty of Information Technology
University of Petra

Technical Writing

Documents Types
Part III
Course No.: 601201
Prerequisite: 402102

Based on:
The Mayfield Handbook of Technical and Science Writing
Leslie C. Perelman, James Paradis Edward Parrett,
Mayfield Publishing Company, Inc.
Technical Report Writing Today
Pauley, Riordan, Houghton Miffin Company USA, 1998

2007/2008 Dr B. Haddad
Faculty of Information Technology
1
University of Petra
 Saleh Fareed
Planning and Producing Documents

Planning
I. First, establish basic criteria.
-Such as Accuracy, Clarity, Conciseness, Coherence, appropriateness

II. Identify the specific purpose of the doc.

-Why are you writing, The Reasons for writing?
-Determine the Objectives

iii. Focus on the Statement of the Problem

-Vague problem definition leads to unsuccessful proposals
- Naming a topic is not the same as defining a problem. (s. exam.)

IV. Determine Doc. General Type (Memoranda, Literature

Reviews, Reports, Research Reports, Research Articles,
Progress Reports ,Technical-Information Letters

V. Define your audience

-Then determine your audience's level of expertise
(experts, technicians, managers , laypersons)
-Attitude to you. It is also important to assess the of the audience
toward both you . (are you expert in his view, or he doesnt know you

VI. Sketch out a preliminary outline to organize it.

-Keeping purpose and audience in mind.
-Sketch out graphics and tables to display your important data.

vii. Write a first draft. At this point in the

process, do not be overly concerned about grammar,
style, or usage. (Using your outline and preliminary graphics)

viii. Finally, edit your paragraphs and sentences to improve their

clarity, conciseness, and coherence, and to fix any problems in
grammar, spelling, punctuation, mechanics, or usage.

ix. Reviews. The last major step for most technical documents is one
or more Reviews
2007/2008 Dr B. Haddad
Faculty of Information Technology
2
University of Petra
 Saleh Fareed
VI. Sketching Doc Organization and outlines

Doc Organization

Organization is the arrangement of elements into

structure

Doc Organization
is ensuring is

Work strategy for Coherence of Document planning

setting priorities Introductory Develop Outline for
Use Work plans as Body General Structure
Aids for producing Conclusion and Section
A schedule (in
Proposals,
Progress reports

We will discuss Work plan later in Elements of Technical Documents

2007/2008 Dr B. Haddad
Faculty of Information Technology
3
University of Petra
 Saleh Fareed
Collaborative Writing

Done not by individuals but by various types of groups.

It has both benefits and pitfalls.
-Interaction among members of a writing group often stimulates creativity
and scientific insight.
-its dangers. In any group activity, there are problems of scheduling,
communication, and conflicts

collaborative writers might need to incorporate the following

steps into the process of writing their document.

1) List all research and writing tasks necessary for completing the project.
2) Determine which tasks depend on the completion of other tasks.
3) Establish a realistic schedule for completing the document.
4) Assign tasks to individual members of the group.
5) Develop a style guide for distribution to ensure a consistent format and
style.
6) Determine procedures and responsibilities for the document's production
and final electronic form.
7) Assign someone to manage the document's production.
8) Establish procedures for reviewing each other's sections as they are
written.
9) Assign someone to be responsible for consistency and accuracy in style.
10) Assign someone to be responsible for technical accuracy.
11) Develop procedures for resolving possible conflicts.

These procedures are often incorporated in a document plan.

2007/2008 Dr B. Haddad
Faculty of Information Technology
4
University of Petra
 Saleh Fareed
Legal and Ethical Issues

TW: sometimes poses unexpected legal and ethical problems

Here are some things to keep in mind

Be aware of the differential of expertise.

- The expert assumes an authority and uses a language that
the layperson is usually not able to judge he might fail to point out
alternatives , to give the whole picture, acknowledge gaps in logic , to
cite or credit sources
Be specific about deliverables.
- Generally, you need a specific written agreement about what will be
accomplished in your work. Otherwise you might easily find
yourself in a contested situation

Keep clear and well-organized records

- Written records and communication are widely accepted means of
establishing accountability (responsibility)
Be aware of potential sources of plagiarism.
- It is the copying, whether deliberate or unintentional, of ideas or
portions of text without citing the sources for credit. It is also the use of
other people's ideas without attributing them to the proper source.
Although plagiarism is often unintentional, it still demonstrates
incompetence. If you fail to record your sources and then later forget
that you used a source, you are still liable and open to the charge of
theft of intellectual property.

2007/2008 Dr B. Haddad
Faculty of Information Technology
5
University of Petra
 Saleh Fareed
Document Design

Document design to help readers locate information and understand the

structure and meaning of your material

Aspects of Do. Design

Informational Aspect Physical Aspect (physical appearance)

Format Layout
Refers to the arrangement of the Shape and form of the document
Document's content into standard subject (arrangement of Doc pages and setup)
areas such as Page and the (Page layout)
Introduction Document as a whole.

Theory, method and results Page layout such as

Discussion, and headings
numbering systems
Conclusions sections bullet and enumerated lists
General design of standard document white space
elements such as columns, margins, fonts, indentation,
justification
Tables and
Figures, as well as Total physical design

Citations Covers paper size and quality

(parenthetical references, footnotes and colors,
bibliographies).
Format conventions are usually widely followed two-sided printing may
but may vary from field to field.
Usually we should use standardized formats for
the arrangement of material such standard report:
-Title page
-Abstract See Example
-Table of Content and so forth
NEXT will be Doc. Type and format

Outline consideration Final Version

2007/2008 Dr B. Haddad
Faculty of Information Technology
6
University of Petra
 Saleh Fareed
Document Design

Page Layout Example

and footer

Capital letters, italics,

--V. Pletser, "Aircraft Parabolic Flights," European Space Agency Bulletin, in The Mayfield Handbook
of Technical and Science Writing
Leslie C. Perelman, James Paradis Edward Parrett, Mayfield Publishing Company, Inc.

2007/2008 Dr B. Haddad
Faculty of Information Technology
7
University of Petra
 Saleh Fareed

2007/2008 Dr B. Haddad
Faculty of Information Technology
8
University of Petra
 Saleh Fareed

( Label Heading )

2007/2008 Dr B. Haddad
Faculty of Information Technology
9
University of Petra
 Saleh Fareed

Document Types

After identifying a document's purpose, determine the appropriate document type

Memoranda
Agendas
Meeting documents
Literature reviews
Reports
Letters
Proposals
Press releases
Specifications
Documentation
Instructions and procedures
Style guides
Theses
Oral Presentations
Rsums
Notebooks
Or to
Electronic document types
such as:
Electronic mail
Web sites
Hypertext

2007/2008 Dr B. Haddad
Faculty of Information Technology
10
University of Petra
 Saleh Fareed

Document Types

Memoranda
Memoranda are brief, informal reports used to establish a record.
They generalize the communication process by transmitting the
message from one or more authors to one or more recipients.
E-mail messages typically take the form of memoranda.
Memoranda are written for numerous internal purposes
For Example
- to request information,
- to make announcements,
- to outline policies, and to transmit meeting minutes.

Thus, in most organizations, memos play a crucial role in establishing a record of

decisions, requests, responsibilities, results, and concerns.

Example
The Memo Heading
The distinctive element of the memorandum is its heading, which is used to outline
the message in a very accessible and transparent way

2007/2008 Dr B. Haddad
Faculty of Information Technology
11
University of Petra
 Saleh Fareed
Memoranda

The Memo Body

The memorandum should normally begin with a
-brief summary statement,
- in one or two sentences, identifying the key topic and the scope of the memorandum.

See detail next page

2007/2008 Dr B. Haddad
Faculty of Information Technology
12
University of Petra
 Saleh Fareed
Memoranda

The Memo Body

The Mayfield Handbook

of Technical and Science Writing
Leslie C. Perelman, James Paradis Edward Parrett, Mayfield Publishing Company, Inc.

2007/2008 Dr B. Haddad
Faculty of Information Technology
13
University of Petra
 Saleh Fareed
Meeting documents

The two principal meeting documents are the

Agenda, which tells participants what topics will be discussed at the meeting
Minutes, which record what actually occurred.

Agenda
1)Report by Dr Susan on investigation of possible security
software
2)Report by Prof. Nazmi and DrS. Maram on development
of database prototypes
3)Discussion of possible hardware platforms
4)Review of deadlines for project
5) Agenda for next meeting

2007/2008 Dr B. Haddad
Faculty of Information Technology
14
University of Petra
 Saleh Fareed

Literature reviews

Summarize existing printed or electronic information on a specific subject in a

literature review
A literature review may be a self-contained document, or it may be a
Section of a larger Report.
Informing the colleagues and manager (or whatever) of current
information on a subject to prevent needless duplication of work

Recommendations

Begin with an introduction that gives reader the context and scope of your
specific topic.

Make the review as concise as possible and eliminate any unessential

material.

End a self-contained literature review with a conclusion that summarizes

the information that is most important to the reader.

Cite all references in the appropriate format, and include all sources in a
bibliography or works-cited section at the end of the document.

Organize a literature review either chronologically or by dividing the topic

into subtopics and then presenting the subtopics in order of importance,
starting with most important subdivision.

See the following Example

2007/2008 Dr B. Haddad
Faculty of Information Technology
15
University of Petra
 Saleh Fareed
Literature reviews: Example

Forecasting st

Scope

2007/2008 Dr B. Haddad
Faculty of Information Technology
16
University of Petra
 Saleh Fareed

References

The Mayfield Handbook of Technical and Science Writing.

2007/2008 Dr B. Haddad
Faculty of Information Technology
17
University of Petra
 Saleh Fareed
Reports

Reports are standard documents in all organizations.

A report is a stand-alone document that records the results of a factual
inquiry to other parties (such as manager, supervisors, )
Because a report typically circulates as an independent document, it will
typically follow a standard format that begins with a front matter section
that orients the reader to the main purpose and content of the report,
followed by a report body, followed by end matter.
Reports may be internal or external, informal or formal.
(The informal report circulates within the local environment and is
generally not written about externally funded research. )
(The material of an internal report often takes the form of a memorandum),
which is a stripped-down version of the internal report, using a standard
header.
Formal reports are generally tightly structured and extensively reviewed
before they are released. Report structure may vary according to the
intended audience.

Type of Reports

Laboratory reports
Research reports
Research articles
Design and feasibility reports
Progress reports
Consulting reports
Trip reports

See Examples
2007/2008 Dr B. Haddad
Faculty of Information Technology
18
University of Petra
 Saleh Fareed

Laboratory reports: Example as Memorandum

The Mayfield Handbook of Technical and Science Writing.

2007/2008 Dr B. Haddad
Faculty of Information Technology
19
University of Petra
 Saleh Fareed
Research Reports

Research reports present the results of formal investigations into the

properties, behavior, structures, and principles of material and conceptual
entities.
The following are some key differences between formal research, and
other less structured kinds of inquiry.
1. Problem definition: the rigorous reduction of the inquiry to a
narrow question with a quantifiable answer. The most significant
preliminary phase of research writing is that of effective problem
definition. This process is one of identifying an interesting question
and narrowing the research inquiry to a manageable size.
2. Research approach: the structuring of the research according to a
methodology associated with a specialized field of inquiry.
Specialized fields have research methodologies that are followed in
investigating problems. These range from general methods of
interviewing and literature researching to highly specialized
procedures for using materials and mechanical devices to establish
appropriate conditions for generating data. Adapting a sound
research methodology to the investigation of your problem is a major
milestone in the conduct of your inquiry.
3. Research report: the presentation of the research and its results in a
rigorously formatted document that follows a conventional structure.
In presenting your research, you pull all its elements together into a
focused, coherent document. Research reports contain a standard set
of elements that include
- Front matter
-Body
-End matter

See Examples

2007/2008 Dr B. Haddad
Faculty of Information Technology
20
University of Petra
 Saleh Fareed
Research Reports: Example

2007/2008 Dr B. Haddad
Faculty of Information Technology
21
University of Petra
 Saleh Fareed
Research Reports: Example

2007/2008 Dr B. Haddad
Faculty of Information Technology
22
University of Petra
 Saleh Fareed

2007/2008 Dr B. Haddad
Faculty of Information Technology
23
University of Petra
 Saleh Fareed

2007/2008 Dr B. Haddad
Faculty of Information Technology
24
University of Petra
 Saleh Fareed

2007/2008 Dr B. Haddad
Faculty of Information Technology
25
University of Petra
 Saleh Fareed

The Mayfield Handbook of Technical and Science Writing.

2007/2008 Dr B. Haddad
Faculty of Information Technology
26
University of Petra
 Saleh Fareed
Front matter

The front matter is the "envelope" of your document

(The elements that make up the front matter introduce
the reader to the body of your document)
They help the reader understand a document's
Who the Author
What the problem
Why argument
Where organization
How method

This first part of a document is, from the reader's

standpoint, the most important.
(It tells him or her what your topic and purpose are, how
your material is arranged, and where to locate items of
interest

2007/2008 Dr B. Haddad
Faculty of Information Technology
27
University of Petra
 Saleh Fareed
Front matter

The following table lists some typical elements contained in the front
matter of various documents ( s.t=sometimes).

Report Article Proposal Memo

Title yes yes yes yes
Abstract yes yes yes no
Executive summary s.t no s.t no
Table of contents yes no yes no
List of figures yes no yes no
List of tables yes no yes no
List of terms s.t s.t s.t s.t
Acknowledgments s.t s.t s.t no

The Mayfield Handbook of Technical and Science Writing.

2007/2008 Dr B. Haddad
Faculty of Information Technology
28
University of Petra
 Saleh Fareed

Body

The body of a document consists of all material necessary for the document
to fulfil its
Explicit (establishing trust)
Implicit goals (informing, convincing documenting actions)

The body of a document may include the following sections:

Introduction
Background
Theory
Design and Decision Criteria
Materials and Apparatus
Procedure
Work Plan
Results
Discussion
Conclusion
Recommendations

2007/2008 Dr B. Haddad
Faculty of Information Technology
29
University of Petra
 Saleh Fareed

Body

Introduction

The introduction to your document should lead your readers into your
paper and give them an idea of what to expect ( Forecasting).
It should not be simply a restatement of the abstract even though it
will contain some of the same material.

Introductions often do the following:

State the subject of your document as clearly as possible

Define the problem you are addressing, your approach to the problem,
and why this problem is important
State the purpose of your document
Define the scope of your document
Provide necessary and relevant background information

2007/2008 Dr B. Haddad
Faculty of Information Technology
30
University of Petra
 Saleh Fareed

Body

Introduction

Sample Title and Introduction: Information Systems Report:

A New Procedure for Ensuring Data Integrity in Flight Reservation Systems

In the current flight reservation system, a remote operator performs 5-15

transactions to arrange a flight reservation before finally sending an "end-
transaction" message. This final message serves as a commit message to the server,
which then records the transaction to disk and modifies its database. Before the end-
transaction message is sent, the reservation data is held on the system's local disk. In
the event of a system crash, the main processor (or a lower performance backup
processor) reboots and resumes communication with all agents. However, this
procedure has no mechanism for dealing with unfinished transactions, and,
consequently, a system crash may produce inconsistent data between the remote
operator's client and the reservation system's server.

The airline currently uses three separate procedures to prevent and address these
inconsistencies. First, it instructs all agents that when a system crash occurs, they
should erase the entire transaction and resubmit it. Second, the airline runs certain
consistency check algorithms every night off-line. These algorithms, however, are
simply best-guess estimates and will not identify most unfinished transactions.
Finally, all reservations, including unfinished transactions, are copied onto magnetic
tape. If a customer complains about inconsistency, the airline can check this record.

State of art: Background

[the document's problem statement]

2007/2008 Dr B. Haddad
Faculty of Information Technology
31
University of Petra
 Saleh Fareed

Body

Background

Provide enough information in a technical document to allow your reader to

understand the specific problem being addressed and to provide a context for
your own document.
This background information may include:

A) a historical summary of the problem being addressed;

B) a brief summary of previous work on the topic, including, if
appropriate, relevant theory; and
C) the specific reasons the document is being written.

NOTE:
In short documents, include background information in the
introduction.
In longer documents, however, putting some or all of the background
information in a separate section with a heading may be more
effective.

2007/2008 Dr B. Haddad
Faculty of Information Technology
32
University of Petra
 Saleh Fareed

Body

Background: Example

1.1 Historical Perspective

Historically, the issue of modes in human computer interaction emerged as
more and more functions were added to early word processors, and yet the
size of the interface (e.g., number of function keys, screen area, etc.) stayed
constant. One solution was to use the same key to engage several commands;
this was implemented by providing the user with some mechanism to switch
the application from one mode to another. Depending on the mode, hitting the
same key would execute different commands. In this paper the term
format/data-entry modes is used to describe this type of mode
implementation. For example, the vi text editor has two modes of operation:
"Command" and "Insert." In "Command" mode, pressing the "x" key will
delete a character; in "Insert" mode this action will write the letter "x" on the
screen.
Users of these early applications, however, were not always happy with such
mode implementations: errors, or mode-errors, as these were termed by
Norman (1981), caused confusion and frustration (Lewis, and Norman, 1983).
Tesler (1981) captured this growing frustration in his influential article in
Byte magazine and his pointed cry: "don't mode me in." Research on modes
in the human computer interaction literature has mostly focused on various
implementations for the mode switching mechanism (Monk, 1986;
Thimbleby, 1982). The problem, nevertheless, has not disappeared: designing
efficient modes and switching mechanisms continues to be part of any
human-computer interface.
The same growing pains are now shared by designers and operators of
supervisory control systems. Since most supervisory control systems are
managed via a computer, format/data-entry modes for input of information
and display switching are heavily used. But in most supervisory control
systems there is also another type of mode: one that is used for controlling the
process. This unique mode is the method used for engaging various control
behaviors (e.g., reverse/drive gears in a car). In this paper, the term control
modes is used to describe this type of implementation.
--A. Degani et al., "Mode Usage in Automated Cockpits: Some Initial Observations," Proceedings of
the International Federation for Automatic Control (IFAC)

2007/2008 Dr B. Haddad
Faculty of Information Technology
33
University of Petra
 Saleh Fareed

Body
Theory
In long and fairly complex reports and articles, especially theoretical and
experimental reports where the purpose of the document is to apply, verify,
or illustrate one or more theories, include a separate section presenting
relevant theoretical formulae and the techniques by which any experimental
results are predicted.
When introducing equations, be sure to define all symbols used in them.
Example

Attitude Display Implementation

The graphics display created for this experiment presented attitude
information to the pilot in the HMD [helmet-mounted display]. For the
purpose of the experiment, no other information (e.g., airspeed,
altitude) was presented during the actual data collection. The attitude
display consisted of a pitch ladder, velocity vector symbol, and
waterline symbol (fig. 3).
With the conformal attitude presentation, the appearance of the
displayed information was dependent on the head position of the pilot.
The displayed horizon line of the attitude symbology, if it was in view,
would always overlay the horizon of the outside scene. If the line of
sight of the pilot was not aligned with the body axis of the airplane, the
attitude of the airplane . . . could not always be easily obtained from
the displayed symbology.
With the body-axis concept, no matter which direction the pilot moved
his head, the display appeared as if the pilot was looking directly out
the front of the airplane. In essence, the body-axis concept was
analogous to physically mounting a HUD [head-up display] to the
helmet. With this concept, the pilot could always directly determine the
attitude of the airplane. However, in situations where the line of sight
of the pilot was not aligned with the body axis of the airplane, the
displayed horizon line of the attitude symbology, if it was in view,
would not overlay the horizon of the outside scene.

--D. Jones et al., "Concepts for Conformal and Body-Axis Attitude Information for
Spatial Awareness Presented in a Helmet-Mounted Display," National Aeronautics
2007/2008 Dr B. Haddad
and Space Administration
Faculty of Information Technology
34
University of Petra
 Saleh Fareed

Body
Theory

Heading
EQ. Number

2007/2008 Dr B. Haddad
Faculty of Information Technology
35
University of Petra
 Saleh Fareed

End Matter

End matter consists of material outside the main body of the

document that may furnish useful references to the reader.

Three of the most common types of end matter are

References
Appendixes
Indexes

References

There are two basic and universal rules regarding the use of information in
professional and, especially, academic writing:

If you use the language of your source, you must quote it exactly, enclose
it in quotation marks, and cite the source.
If you use ideas or information that are not common knowledge, you must
cite the source.

2007/2008 Dr B. Haddad
Faculty of Information Technology
36
University of Petra
 Saleh Fareed

End Matter

Appendixes

In one or more appendixes, include materials that are not essential parts of
your main text but that will provide useful reference information to readers
seeking more detail.
The following list presents some typical material that is often included in
an appendix:
Detailed explanations and elaborations too technical for the main text
Additional diagrams
Additional tables summarizing data
Long lists
Experimental protocols or survey questions
Selected computer code directly relevant to discussions in the main
body

Guidelines for Appendixes

Avoid using appendixes as dumping grounds for raw data that you will be
unable to incorporate in the body of the paper.
If you have more than one appendix, use letters to label them
(Appendix A, Appendix B, and so forth).
Give each appendix an appropriate title.
Place one specific kind of information in each appendix.
Begin each appendix on a new page. (if appropriate)
If appropriate, identify and summarize the contexts of an appendix in a
short summary paragraph.
Refer to each appendix in the body of the document.

2007/2008 Dr B. Haddad
Faculty of Information Technology
37
University of Petra
 Saleh Fareed

End Matter

Indexes

Use well-structured indexes to make material in long documents

accessible to your audience.
Indexes are extremely useful tools for allowing a reader to retrieve
all important information.

Guidelines for Constructing an Index

Use features available in most word processors to mark items that should be
included in an index. (Win-WORD)
Include every important subject, topic, subtopic, and proper name in the
index.
Most indexes consist of two levels of entries, a main heading and a
subheading:

Operating systems
DOS
DOS/Windows
UNIX
Linux

Use cross-references in appropriate places in the index to guide the reader to

related information in the book:

Word processors
MS Word
Text pad
WordPerfect (See also Editors)

2007/2008 Dr B. Haddad
Faculty of Information Technology
38
University of Petra
 Saleh Fareed
Body

Design and Decision Criteria

Usually included in feasibility reports, recommendation reports,
proposals, and other documents that are concerned with the possible
design of a product or, in some cases, a future course of action.
Managers use these criteria as their basic tool in evaluating a project's
potential for success and how well it fits into the goals of the
organization. Experts need explicit design and decision criteria in order
to evaluate recommended designs of devices and test procedures.
Make your design criteria short but as specific as possible.
Avoid vague language. List your primary criteria first (essential); then
list the secondary criteria (highly desirable criteria).
Often design criteria are best displayed in bulleted lists, with short
titles preceding the explanation. These titles may then be used later in
the document to refer to the specific criteria being discussed.

2007/2008 Dr B. Haddad
Faculty of Information Technology
39
University of Petra
 Saleh Fareed
Body

Design and Decision Criteria

Example

4.0 Design Criteria

The online shopping system must possess the following features:
Real time transactions of food, books and notes. The system will enable real-
time purchases of meals through university ID cards, textbooks and supplies
either through ID cards or through the campus network, and purchase and
delivery of online course notes through the campus network.
Real-time debiting and crediting of accounts. At the time of purchase, the
system will debit the user's account for the amount of the sale and credit the
appropriate vendor's account.
Authentication of user and server. The system server will always authenticate
both the user to the server and the server to the user.
Data security. All sensitive data must be encrypted before being passed
between the client and server; no sensitive data will be sent through the network
in clear text.
In addition, the system should, if possible, possess the following additional
features:
Compatibility with existing browsers. Users should be able to access the
system using any commonly available network browser.
Direct inventory interfaces. The system should be able to interface directly with
the various inventory systems of the vendors to allow real-time authentication
that the item is in stock and, when the transaction is completed, removal of the
item from vendor's current inventory.

The Mayfield Handbook of TW.

The first primary criterion describes the essential operation of the system.
The second, third, and fourth primary criteria list features that are necessary for the system
to operate successfully.
Two secondary criteria are then listed as desirable additional features.

2007/2008 Dr B. Haddad
Faculty of Information Technology
40
University of Petra
 Saleh Fareed
Body

Materials and Apparatus

In documents that describe an experiment or other procedure, list all
hardware and software in sufficient detail for the reader to reproduce the
process.
Describe equipment and software specific to the procedure.
In many cases, essential information on materials and apparatus can be
most effectively presented in a table.
In short documents, describe materials and apparatus as part of the
procedures section.
Put lengthy descriptions of materials and apparatus in one or more
appendixes, referring to these descriptions in the main text.

Procedures
Describe in detail experiments or other methods of collecting data.
The purpose of the procedure section is to allow a reader of the report to
reproduce the experiment or data collection process.
The procedure section should be written in narrative form with illustrations
of all test setups and procedures included within the text
As in all narratives, organize the material to follow the actual sequence of
events. Separate each group of actions into one or more paragraphs, and
describe each discrete action in one or more sentences.

2007/2008 Dr B. Haddad
Faculty of Information Technology
41
University of Petra
 Saleh Fareed
Body

Procedures: Example

Non-Word Correction

The process of non-word correction can be interpreted as a transformation

process of a non-word into a valid root-pattern relationship using different
transformation operations considering the different types of the basic single
errors in connection of morpho-syntactical, and/or

morphographemic rules. In
our view, such an error detection strategy seems to be more natural and faster
in predicting the intended word formalization. The root and pattern analysis
procedures are working interrelated to each other.
As soon as patterns are proposed, the root filtering process will be invoked
to propose roots from non-word characters, which subsequently will be
checked for root-pattern consistency and only root-pattern instantiations with
proper valid substitutions satisfying their constraints rules will be considered
as possible candidates.
To generate roots or stems from a non-word, the transformation operator
will be applied primarily to all possible root or stem characters utilizing the
conflict sets. This process will try to predict the deformation in the root
characters under the assumption that the incorrect root resides on a basic
single error misspelling. Application of the transformation operator will start
with the most probable single error procedure; i.e. Substitution, and then with
deletion if the substitution procedure fails to create a valid root, etc. As this
process is based on firing all probable patterns from non-word, it guarantees
to consider all single-error and the most multi-error misspellings.
The problem of proposing a root or a pattern becomes more complicated if
both root, or stem and pattern are multiple deformed. Relying on the conflict
sets and the possible valid root-pattern characters contained in the non-word
and in connection of their root-pattern predictive probabilistic values, this
procedure will try to predict the most likely root given some pattern and the
most likely pattern under a particular root. In this case, it is probable to
propose many correction candidates, which need to be ordered after a ranking
strategy.

Process

2007/2008 Dr B. Haddad
Faculty of Information Technology
42
University of Petra
 Saleh Fareed
Body

Example: Experimental Procedures

CNBr mapping was performed on immunoprecipitated pleckstrin which was gel-purified

by SDS-polyacrylamide gel electrophoresis. A gel slice containing the phosphopleckstrin
was mixed with 50 mM ammonium carbonate (pH 8.5), 0.1% SDS, 1% mercaptoethanol.
Pleckstrin contained in the eluate was passed through glass wool, trichloroacetic acid-
precipitated, washed twice with a 50:50 mixture of cold ethanol:ether, and then vacuum-
dried. The sample was resuspended in 30 l of 50 mg/ml CNBr in 70% formic acid and
incubated at room temperature for 1 h. At this point, the digest was lyophilized with 1 ml
of distilled water and again vacuum-dried. When noted, the CNBr fragments were
further digested by incubating them overnight in the dark at room temperature in 30 l of
10 mg/ml iodosobenzoate (IBZO) in 80% acetic acid with 4 M guanidine HCl(26). All
samples were then lyophilized with 1 ml of distilled water, vacuum-dried an additional
three times, and fractionated on a Tricine gel(27).
--S. Abrams et al., "Protein Kinase C Regulates Pleckstrin by Phosphorylation of Sites
Adjacent to the N-terminal Pleckstrin Homology Domain," Journal of Biological
Chemistry

2007/2008 Dr B. Haddad
Faculty of Information Technology
43
University of Petra
 Saleh Fareed
Body

Work Plan (project plan)

A project plan outlines in specific detail how a project will be conducted,

who will work on which part, and when and in what order each part will
be accomplished. It is similar to a procedure section but differs in that it
describes future rather than past actions

Include a work plan as a separate section in all lengthy proposals.

Preliminary project plans are also sometimes appropriate in feasibility
and recommendation reports.
Most progress reports refer to all or part of previously existing project
plans.
Most project plans include the following elements:
A short description of the project's objective
A list of personnel participating in the project
A list of all equipment and facilities to be used in the project
A breakdown of the project into specific tasks, with indications of
which tasks are dependent upon the completion of others
A schedule indicating when each task will be started and when it
will be completed and who will perform it; this information may be
represented as an annotated bar chart
A Budget

2007/2008 Dr B. Haddad
Faculty of Information Technology
44
University of Petra
 Saleh Fareed
Body

Work Plan (project plan): Example

2007/2008 Dr B. Haddad
Faculty of Information Technology
45
University of Petra
 Saleh Fareed

The Mayfield Handbook of TW.

2007/2008 Dr B. Haddad
Faculty of Information Technology
46
University of Petra
 Saleh Fareed
Body

Results
In the results section of a report, describe all appropriate information
produced by the research procedures.
present data and estimates of their accuracy.
Save the explanation and interpretation of these findings for the discussion
section, which usually follows the results section.
In short documents, however, the results and discussion sections may be
combined into a single section.
Results sections make extensive use of graphs and figures to present data
effectively.
Order information by its importance to your audience's purpose in reading
the document.
State all significant findings in the text, referring to tables and graphs
displaying all significant data.
If the study has produced a large amount of raw data, do not present all of
it in the results section. Instead, present only the information most
appropriate to your audience's purpose in reading the document,
summarizing other key information in graphs and figures.
If appropriate, include your raw data in an appendix, referring to them
within your text.

Summation of Results
The quantitive results of this study favored the body-axis concept. (See
Fig. 5.) Although no statistically significant differences were noted for
either the pilots' understanding of roll attitude or target position, the
pilots made pitch judgment errors three times more often with the
conformal display. The subjective results showed the body-axis display
did not cause attitude confusion, a prior concern with this display. In the
posttest comments, the pilots overwhelmingly selected the body-axis
display as the display of choice.
--D. Jones et al., "Concepts for Conformal and Body-Axis Attitude
Information for Spatial Awareness Presented in a Helmet-Mounted
Display," National Aeronautics and Space Administration

2007/2008 Dr B. Haddad
Faculty of Information Technology
47
University of Petra
 Saleh Fareed
Body

Discussion
Explain in the discussion section of your document information presented
in the results section, commenting on significant data produced by the
study.
In writing a discussion section, keep the following points in mind:

Identify significant patterns in the data and relationships between

variables.
Offer tentative explanations for these patterns and relationships.
Compare the actual data produced with any predictions or questions
posed in the introduction or theory section of the document.
If any of the results differ from the expected results, offer possible
explanations for the discrepancies. Present the most probable
explanations first and the least probable last.
Consider how well the data answer any questions posed in the
document's introduction. Do the results answer the questions
completely? If not, explain what questions still need to be addressed
and give possible explanations why the results may be inconclusive.
Qualify the scope of your explanations, discussing in what cases
your explanations apply and in what cases they may not.
Organize your material in order of importance to your reader's
purpose in using the document.

2007/2008 Dr B. Haddad
Faculty of Information Technology
48
University of Petra
 Saleh Fareed
Body

Discussion Example

Discussion
The major finding of our current work is that inhibition of SL synthesis
and degradation have opposite effects on the formation or stabilization
of collateral axonal branches. In contrast, no effect is observed on the
formation of the parent axon during its emergence from the cell body.
The fact that inhibition of SL synthesis and degradation affect growth
in hippocampal neurons is not entirely unexpected. SLs have been
implicated in a variety of cellular phenomena, including cell-cell
interaction, differentiation, and adhesion (7, 34). Addition of
exogenous SLs, particularly GMs, has dramatic effects on neuronal
growth in primary neuronal cultures and in neuroblastoma (8). It has
also been demonstrated that accumulation of SLs in animal models of
lysosomal storage disorders is accompanied by abnormal appearance
of ectopic dendrites at the axonal hillock (35). Manipulation of
endogenous SLs in hippocampal neurons might therefore be predicted
to affect growth, as has been observed in cells and tissues of non-
neuronal origin (16, 17, 18, 36, 37) and in neuroblastoma (38).
However, ours is the first study that implicates SL metabolism in a
particular facet of neuronal growth, namely collateral branch formation
or stabilization.
--Andreas Schwarz et al., "A Regulatory Role for Sphingolipids in
Neuronal Growth," Journal of Chemical Biology

2007/2008 Dr B. Haddad
Faculty of Information Technology
49
University of Petra
 Saleh Fareed
Body

Conclusion

Include a conclusion as the final part of the body of your document.

Because some readers of documents, particularly managers, will
sometimes not read the entire document but, instead, focus on the
conclusion, this part of the document should summarize all essential
information necessary for your audience's purpose.
In your conclusion:
Relate your findings to the general problem and any specific
objectives posed in your introduction.
Summarize clearly what the report does and does not demonstrate.
Include specific recommendations for action or for further
research.
Sometimes these recommendations will constitute a separate
section of a document.

Example: Short Conclusion

In conclusion, we have demonstrated that SLs, particularly glyco-SLs, are

involved in the formation or stabilization of axonal branches in cultured
hippocampal neurons. We are currently examining the levels and types of
SLs synthesized during development, and their targeting to axonal or
dendritic domains, in order to distinguish between the various possible
molecular mechanisms that could account for these effects.
--Andreas Schwarz et al., Journal of Chemical Biology

Homework: Give different examples for long and short

Conclusions by extracting them from International Journals for
Computing you know.

2007/2008 Dr B. Haddad
Faculty of Information Technology
50
University of Petra
 Saleh Fareed
Body

Recommendations
Include appropriate and specific recommendations as part of your
conclusion or, in feasibility and recommendation reports, as a separate
section preceding the conclusion.
Many types of scientific and technical documents conclude by pointing to
further action. Research reports often recommend further studies to confirm
tentative explanations or to answer questions presented in the discussion
section.
Feasibility and recommendation reports always have one or more specific
recommendations as the principal aim of the document.
Recommendations should always be specific and appropriate to the
document's audience. Separate each specific recommendation.
Often authors present recommendations in bulleted or numbered lists.
Organize recommendations either in the order of importance or in the
logical order of development.

2007/2008 Dr B. Haddad
Faculty of Information Technology
51
University of Petra
 Saleh Fareed
Progress Reports

Main objectives of progress Report :Project monitoring and accountability

The typical progress report gives some summary of the project goal, states
the progress made toward that goal during the reporting period, discusses
significant costs and scheduling issues, and lists future objectives to be carried
out.
Generally, progress reports are prepared at intervals, most frequently at
quarterly intervals of the fiscal year. The intervals are often specified in the
initial project proposal.
Consultants use progress reports to maintain contact with sponsors.
Research organizations use progress reports to inform funding organizations,
government or commercial, of their work progress.
Internal research workers use progress reports to report on their work to
managers and others within their own organizations.
Progress reports are useful tools for management in keeping track of work
progress in their groups, and they also furnish researchers a structure for
monitoring their own commitments and levels of support.

Format of Progress Reports

The general format of progress reports varies widely from an informal
business letter giving an update on work accomplished to the highly
detailed formal structure required by funding agencies at specified
intervals.
The sequence of information is often as follows:

Front matter( Project title, funding source, contract number, funding

period, report date, research organization, and funded staff)

Body. (Project summary, overview, report of progress, problems (cost or

schedule issues), future work

End matter (References, attachments)

2007/2008 Dr B. Haddad
Faculty of Information Technology
52
University of Petra
 Saleh Fareed
Progress Reports

Example

2007/2008 Dr B. Haddad
Faculty of Information Technology
53
University of Petra
 Saleh Fareed

The Mayfield Handbook of TW.

2007/2008 Dr B. Haddad
Faculty of Information Technology
54
University of Petra
 Saleh Fareed
Progress Reports

Example

Progress of a Project

2007/2008 Dr B. Haddad
Faculty of Information Technology
55
University of Petra
 University of Petra
Faculty of Information Technology

Dr. techn. Dipl. Inform. Bassam Haddad

Associate Professor of Computer Science
Faculty of Information Technology
University of Petra

Technical Writing

Documents Types III

Part V
Course No.: 601201
Prerequisite: 402102

Based on:
The Mayfield Handbook of Technical and Science Writing
Leslie C. Perelman, James Paradis Edward Parrett,
Mayfield Publishing Company, Inc.
Technical Report Writing Today
Pauley, Riordan, Houghton Miffin Company USA, 1998

1
2007/2008 Dr B. Haddad
Document Types

After identifying a document's purpose, determine the appropriate document type

Memoranda
Agendas
Meeting documents
Literature reviews
Reports
Letters
Proposals
Press releases
Specifications
Documentation
Instructions and procedures
Style guides
Theses
Oral Presentations
Rsums
Notebooks
Or to
Electronic document types
such as:
Electronic mail
Web sites
Hypertext

2
2007/2008 Dr B. Haddad
Letters

Letters: to communicate outside your organization. Whereas the

memorandum is the primary vehicle for communication within an
organization
letters are often used to communicate to individuals outside it,
especially in formal and semiformal contexts.
Letters are an essential part of all business and technical
communication because they are more formal and reliable than
electronic mail and more precise and permanent than telephone or
face-to-face conversations.

Types of Letters
The following are some of the most common types of letters
written by people in technical fields:

Job application letters

Acceptance letters

Transmittal letters

Inquiry letters

Technical-information letters

Letters of recommendation

3
2007/2008 Dr B. Haddad
 Letters
Format of a Letter
If your organization has a specific style for business letters, follow
that format. Otherwise, follow the guidelines provided here.
Business letters are commonly either full-block formatted, with
every line starting at the left margin and usually a business
letterhead at the top of the page, or modified-block formatted,
with the heading and the closing aligned at the center of the
page.

Elements of a Letter
Business letters have the following elements:
Heading
Date
Recipient's address
Salutation
Body
Closing
End notations

Heading
If you are not using letterhead stationery, begin with your full address
(city, street, and zip code) 1 to 1 inches from the top of the page.
Spell out address designations, such as Street, Avenue, and West
Postal Service designations.
Include the date aligned at left with the address, spelling out the name of
the month.

4
2007/2008 Dr B. Haddad
 Letters

Business letters :

Recipient's Address
Two to four lines below the date, place the following items:

The recipient's title (such as Mr., Ms., or Dr.) and full name
(address a woman who does not have a professional title as Ms.
unless you know she prefers Miss or Mrs.;
if the recipient does not have a title and you are unsure of his or
her gender, omit the title).
The recipient's job title, if appropriate.
The name of the company or institution, if appropriate.
The full address, following the same format as for the address in
the heading.
The recipient's address is always aligned on the left margin.

Salutation
Place the salutation two lines below the recipient's address.
The salutation begins with the word Dear, continues with the
recipient's title and last name, and ends with a colon.
If you are unsure of the recipient's gender and the recipient does
not have a professional title, omit the title and, instead, use both
the first and the last names in the salutation
(Dear Leslie Perelman:).
If you do not know the name of the recipient of the letter, refer to
the department you are writing to
(Dear Technical Support:).
Avoid salutations such as
Dear Sir or Madam:.

5
2007/2008 Dr B. Haddad
 Letters

Business letters :

Body
Start the letter two lines after the salutation.
Body paragraphs should be single spaced with a double space
between paragraphs.
(Indenting the first line of each paragraph is acceptable but is more
informal than the unindented style.)
Be concise, direct, and considerate.
State the letter's purpose in the opening paragraph.
Include supporting information in a middle paragraph or two, and
conclude your letter with a brief paragraph that both establishes
goodwill and expresses what needs to be done next.
If a letter requires more than one page, make sure there are at least
two lines of body text on the final page.
Never use an entire page for just the closing. The second page and all
subsequent pages must include a heading with the recipient's name,
the date, and the page number.

Closing Phrase
Write a complimentary closing phrase two lines below the final
body paragraph.

Yours truly, Sincerely, or Sincerely yours

are common endings
Capitalize the first letter of the first word of your complimentary
closing, and end the complimentary closing with a comma.
Four lines below the closing phrase, write your full name.
If you are writing in an official capacity that is not included in the
stationery's letterhead, write your title on the next line.
Your signature goes above your typed name.

6
2007/2008 Dr B. Haddad
 Letters

Business letters :

End Notations
At the bottom of the last page of a business letter, end notations
may show who typed the letter, whether any materials are enclosed
with the letter, and who is receiving a copy of the letter.
An enclosure notation-
-Enclosure:, Encl., or Enc.--alerts the recipient that additional
material (such as a rsum or a technical article) is included with
the letter.
You can either identify the enclosure or indicate how many pieces
there are
A copy notation (cc:) lets the recipient of the letter know who
else is receiving a copy. Put each recipient of a copy on a separate
line.

Enclosure: Article by Dr Lolo shater

Encl. (2)
Enc. (2)

cc: Dr Fofo Mouse

Mr Lali Mater

7
2007/2008 Dr B. Haddad
 Job Application Letters

Write job application letters that identify a specific area of employment,

summarize your qualifications for the job, refer to an enclosed rsum,
and request the next step of the application process, usually an interview.
Application letters are usually just one page and consist of three
sections:

Front matter. State that you are applying for a specific job title or
field. Also mention the person who referred you or told you about
the job. If you learned of the job from an advertisement, mention
that.
Body. Explain specifically why you are qualified for the job.
Describe education and work experience and any other activities
that display relevant talents, such as foreign-language proficiencies
and leadership or supervisory experience.
End matter. Refer to your enclosed rsum and express your
desire for an interview, stating when and where you will be
available for one. In addition, invite further inquiries, and state how
you can be contacted.

8
2007/2008 Dr B. Haddad
Application letter: An Example

9
2007/2008 Dr B. Haddad
Acceptance letter: An Example

10
2007/2008 Dr B. Haddad
 Transmittal Letters

A transmittal or cover letter accompanies a larger item, usually a document.

(to explain why something is being sent)

Example: A cover letter

11
2007/2008 Dr B. Haddad
Transmittal Letters

Example: A cover letter

12
2007/2008 Dr B. Haddad
Letters of Inquiry

A letter of inquiry asks someone for specific information.

Consequently, always make the tone of the letter friendly and make it
easy for the recipient to identify and provide the information you need.

Format of a Letter of Inquiry

Follow this format in writing a letter of inquiry:
In the first paragraph, identify yourself and, if appropriate, your
position, and your institution or firm.

In the second paragraph, briefly explain why you are writing and
how you will use the requested information. Offer to keep the
response confidential if such an offer seems reasonable.

List the specific information you need. You can phrase your
requests as questions or as a list of specific items of information. In
either case, make each item clear and discrete.

Conclude your letter by offering your reader some incentive for

responding.

13
2007/2008 Dr B. Haddad
Letters of Inquiry: An Example

14
2007/2008 Dr B. Haddad
Letters of Inquiry: An Example

15
2007/2008 Dr B. Haddad
Technical-Information Letters and Memoranda

Technical-information letters and memoranda are short documents that

announce new technical information, such as a software bug and its
solution, or a new feature.
Use the memorandum format if the information is being sent inside an
organization.
Use the letter format if the document will be sent to outside individuals.

The following example is adapted from a technical-information

memorandum written by Information Systems at the Massachusetts
Institute of Technology. The document informs users of MIT's Athena
network of a change in the protocols of MIT's main World Wide Web
(WWW) server that allows users to place shorter Uniform Resource
Locators (URLs) in their WWW pages.

16
2007/2008 Dr B. Haddad
 Rsums

Nearly the most employers read your rsum before they meet you,
and their reaction to it usually determines whether or not they will
consider you further by interviewing you.
In addition, your job interviews will often start with references to your
rsum.
Consequently, spend considerable time in developing one or more versions
of your rsum, each one targeted for a specific type of job.

Your rsum must be readable, neat, and free of grammatical, spelling,

and typographical errors.
Because it is so crucial in the job application process, edit your rsum
carefully and have someone else review it before you send it out.

17
2007/2008 Dr B. Haddad
 Rsums

Effective rsums contain the following elements:

Heading
The heading should contain your name, full address, and phone number,
including area code. If you have them, you may also include a FAX number, an
electronic mail address, and even your World Wide Web page (if you are sure
that you want all prospective employers to see it).
Professional or job objective
The objective statement is a short, one- or two-line description of the sort of job
you want and the specific fields in which you are interested. It does not have to be
a complete
Educational history
Summarize your educational history in reverse chronological order, showing
how it has prepared you for the sort of job you want. List descriptive titles (but
not course numbers) of all relevant classes you have taken. If you have not yet
received your bachelor's degree or if you have just graduated, include the name
of your high school, the city and state in which it is located, and the dates you
attended.
Work experience
List all relevant work experiences in reverse chronological order, using action
to provide vivid and specific descriptions of all activities that are connected with
your job objective.
Your special skills, activities, and accomplishments directly relevant
to your professional objective
List any skill (such as proficiency in a foreign language or expertise in specific
computer applications) that may be relevant to the position. In addition, list any
activity or accomplishment that will provide a positive first impression of
relevant personal qualities, such as your energy level and initiative, your ability
to work with diverse groups of people, and your communication skills. Do not,
however, list hobbies or memberships merely to fill out the rsum. Include only
activities and accomplishments that a prospective employer may find relevant to
the position.
Reference statement
In most cases, conclude your rsum with "References available on request." List
the names of your references only if doing so is customary in your profession and
only if you have secured explicit permission from each individual to include his
or her name on your rsum.

18
2007/2008 Dr B. Haddad
 Rsums

Example 1:

19
2007/2008 Dr B. Haddad
 Rsums

Example 1:

20
2007/2008 Dr B. Haddad
 Rsums

Example 2:

21
2007/2008 Dr B. Haddad
 22
2007/2008 Dr B. Haddad
Action Verbs for Rsums and Job Application Letters

Most employers want to hire active, energetic individuals.

Use action verbs to emphasize and to describe vividly what
you have done and accomplished.

The following list provides a sample of

effective action verbs to use in rsums and job application letters.

acted analyzed assembled assessed

briefed calculated coached compared
compiled composed computed
coordinated created demonstrated
designed developed diagnosed directed
edited established evaluated executed
founded implemented instructed
invented investigated led maintained
managed negotiated operated organized
performed planned prepared produced
promoted reported researched restored
reviewed searched surveyed
synthesized taught tested worked
wrote
.

23
2007/2008 Dr B. Haddad
Proposals

In a proposal, identify a specific problem and state how you will solve
that problem.
Most organizations rely on successful proposal writing for their
continued existence. You will most likely spend a major part of your
professional life writing proposals.
Proposals are carefully prepared and just as carefully reviewed by
granting agencies.
Proposals do not succeed on the strength of a name or as a result of
flashy rhetoric. Rather, successful proposals demonstrate that you
understand the scope of the problem (its background, theory, and
application) and, furthermore, that you have developed a valid and well-
focused approach for reaching proposed objectives.
All proposals develop a plan of action in response to a specific need or
problem. Some proposals are external, written in response to a request for
proposals or an invitation to bid that has been published by an external
organization. Other proposals are internal, written in response to a need
within your own organization. In either case, your proposals must show
that you understand the nature of the problem and that you have a specific
and well-developed plan for arriving at a solution.
Most proposals share a general structure for identifying the motivating
problem, the objectives, and the proposed course of action.

24
2007/2008 Dr B. Haddad
Proposals

General structure

Front matter
Body
Introduction
Technical approach
Management requirements
Work plan
End matter, or management requirements

Front Matter
The front matter of a proposal includes the following components:
Letter of transmittal
Title page
Summary
Table of contents
List of figures and tables

End Matter
Bibliography
Rsums
Appendixes

25
2007/2008 Dr B. Haddad
 Saleh Fareed

University of Petra
Faculty of Information Technology

Dr. techn. Dipl. Inform. Bassam Haddad

Associate Professor of Computer Science
Faculty of Information Technology
University of Petra

Technical Writing
Common Writing Problems for Non-Native Speakers of
English

Part VI
Course No.: 601201
Prerequisite: 402102

Based on:
The Mayfield Handbook of Technical and Science Writing
Leslie C. Perelman, James Paradis Edward Parrett,
Mayfield Publishing Company, Inc.
Technical Report Writing Today
Pauley, Riordan, Houghton Miffin Company USA, 1998

1
2007/2008 Dr B. Haddad
 Saleh Fareed

Common Writing Problems for Non-Native Speakers of English

Article and Noun Problems

Articles
Articles may be divided into two types: definite (the) and
indefinite (a, an). Articles are a type of determiner and
indicate the specificity or nonspecificity of the noun or noun
phrase they modify.

a specific airflow velocity

an electronic circuit
the Greenhouse Effect

Definite Articles
The definite article the signals to the reader that the noun is
specific, not arbitrary, and not new to the reader.

The Greenhouse Effect is a theory in environmental

science which warns of the warming of the globe due
to an increase in carbon dioxide in the atmosphere.

[Only one Greenhouse Effect, one globe, and one

atmosphere are assumed to exist; the context of the
globe serves to make the warming unique.]

Use a definite article if you intend a singular noun to refer to an

entire class of items. Using a definite article with a singular noun
in this way is particularly common with species of animals,
inventions, or musical instruments.

The farm alligator is more dangerous than the wild

alligator because the farm alligator does not fear humans.
-- from "Take It or Leave It,"
2
2007/2008 Dr B. Haddad
 Saleh Fareed

Indefinite Articles

An indefinite article signals that the noun is nonspecific or

that other examples of the noun exist (that the noun is not
unique).
Use an indefinite article (a or an) if a noun is new to the
reader or is an arbitrary example of the class that the noun
belongs to.

An airplane's shadow is virtually the same size regardless of

its altitude.

[An signals that airplane is an arbitrary example, that more

than one airplane exists.]

The Greenhouse Effect is a theory in environmental science

which warns of the warming of the globe due to an increase in
carbon dioxide in the atmosphere.

[Other theories exist; the first time an increase is mentioned, it

is new to the reader.]

3
2007/2008 Dr B. Haddad
 Saleh Fareed

Choosing between a and an

Use a before consonant sounds and an before vowel sounds.
Notice that some words whose first letter is a consonant (for
instance, hour) actually begin with a vowel sound, and other words
whose first letter is a vowel (for instance, unit) actually begin with
a consonant sound.

Unacceptable
a electron, a oxidant, a hour

Acceptable
an electron, an oxidant, an hour

Unacceptable
an chromatograph, an human gene, an unique solution

Acceptable
a chromatograph, a human gene, a unique solution

Make your decision between a and an according

to the first sound of the word that immediately
follows a or an, regardless of the word's
function.

Unacceptable
a electric circuit, an very powerful explosive

Acceptable
an electric circuit, a very powerful explosive

4
2007/2008 Dr B. Haddad
 Saleh Fareed

Nouns

A noun names a person, a place, a thing, or an idea, and is

often preceded by an article (a, an, the).
The words technician, laboratory, equipment, and
hypothesis are nouns.

A noun can be countable or uncountable.

A noun is often preceded by a determiner, which can be an
article, a demonstrative or possessive adjective, or a quantifier.
A noun can be described, or modified, by adjectives.
Nouns can be replaced by pronouns.
Since nouns functioning as subjects can be singular or plural,
their corresponding verbs must agree in number.
Proper nouns are capitalized.

Countable and Uncountable Nouns

Nouns can be classified into two groups, countable and
uncountable.
Countable nouns typically occur as discrete units that can be
counted
whereas uncountable nouns, also called mass nouns, are typically
substances or concepts.

Countable: electron, joule

Uncountable: oxygen, heat, patriotism

Countable nouns can be made plural. Uncountable nouns

are not used in the plural.

Countable: polar regions, transistors, earthquakes

Uncountable: carbon dioxide, infrared radiation,
equipment
5
2007/2008 Dr B. Haddad
 Saleh Fareed

Nouns & Number

You can refer to discrete units of uncountable nouns by adding a

counting word, such as a unit of measurement, or the general word
piece.

Unacceptable
a carbon dioxide; an equipment

Acceptable
a molecule of carbon dioxide; a piece of equipment

Number
Number refers to the singular or plural form.
Keep the number of a noun in mind when choosing pronouns, noun
endings, articles, and subject-verb agreement endings.
Countable nouns can be either singular or plural.
Uncountable nouns can usually appear only in the singular.

Unacceptable
equipments

Acceptable
Equipment

Unacceptable
two electron

Acceptable
two electrons

Unacceptable
hypothesises

Acceptable
hypotheses

6
2007/2008 Dr B. Haddad
 Saleh Fareed

Nouns & Number

When you use a plural noun as a subject, you must use a plural
verb. (Subject-Verb Agreement
Do not use the indefinite article a or an with plural nouns.
(Articles).
When using a pronoun to replace a singular noun that refers
to a person whose gender is unknown
(for example, scientist, student),
be careful to avoid sexist language.
Do not replace a singular noun with the plural pronoun they.
Usually the best course is one of the following:
make the noun (hence the pronoun) plural, use a gender-
free paraphrase such as person, or rephrase entirely to
avoid mention of gender.
When replacing a plural noun with a pronoun, choose the
plural pronoun they.

7
2007/2008 Dr B. Haddad
 Saleh Fareed

Verb Problems

Subject-Verb Agreement

Your verb must agree with your subject in number and person.
If your subject is singular, your verb must be singular
if your subject is plural, your verb must be plural.
If your subject is in the first person, your verb must be in the
first person.
If your subject is in the second or third person, your verb
must agree.

Unacceptable
For more than a century, researchers has known that
exposure to high pressure can injure or kill living
organisms.

Acceptable
For more than a century, researchers have known that
exposure to high pressure can injure or kill.

Unacceptable
mixture of materials were used to withstand high temperatures.
[The subject is mixture, not materials.]

Acceptable
A mixture of materials was used to withstand high
temperatures.

8
2007/2008 Dr B. Haddad
 Saleh Fareed

Pronoun-Antecedent Agreement

A pronoun must agree in gender and number with its

antecedent.
If necessary, vary your choice of pronouns to avoid sexist
language.
Sometimes the best way to avoid sexist language is to change
the singular to the plural.

Unacceptable
In the United States, an astronaut candidate must be
recommended by their previous organization.

Acceptable
In the United States, an astronaut candidate must be
recommended by his previous organization.
Acceptable
In the United States, an astronaut candidate must be
recommended by her previous organization.
Acceptable
In the United States, astronaut candidates must be
recommended by their previous organizations.

9
2007/2008 Dr B. Haddad
 Saleh Fareed

Pronoun-Antecedent Agreement

When the antecedent is a singular indefinite pronoun, use a

singular pronoun to refer to it. In such cases, vary your choice
of pronouns to avoid sexist language. Sometimes the best way
to avoid sexist language is to change the singular to the plural.

Unacceptable
Each of the astronaut candidates sent their photograph with
their application.
Acceptable
Each of the astronaut candidates sent his photograph with his
application.
Acceptable
Each of the astronaut candidates sent her photograph with her
application.
Acceptable
All of the astronauts sent their photographs with their
applications.

When the antecedent is a plural indefinite pronoun, use a

plural pronoun to refer to it.

Unacceptable
Some of the astronaut candidates sent his photograph with his
application.
Unacceptable
Some of the astronaut candidates sent her photograph with her
application.
Acceptable
Some of the astronaut candidates sent their photographs with
their applications.

10
2007/2008 Dr B. Haddad
 Saleh Fareed

Pronoun-Antecedent Agreement

Use a plural pronoun to refer to antecedents joined by the

coordinating conjunction and.

Unacceptable
The ceramic tile and the aluminum alloy used in the
experiment retained its initial hardness.
Acceptable
The ceramic tile and the aluminum alloy used in the
experiment retained their initial hardness.

Use a pronoun that agrees in gender and number with the

closest antecedent to refer to antecedents joined by the
coordinating conjunctions or and nor

Unacceptable
Either the disks or the motor need their parts repositioned.
Acceptable
Either the disks or the motor needs its parts repositioned.
Acceptable
Either the motor or the disks need their parts repositioned.

Use a singular pronoun to refer to antecedents preceded by

each or every.

Unacceptable
Each ceramic tile and aluminum alloy sample used in the
experiment retained their initial hardness.
Acceptable
Each ceramic tile and aluminum alloy sample used in the
experiment retained its initial hardness.

11
2007/2008 Dr B. Haddad
 Saleh Fareed

Pronoun-Antecedent Agreement

Special case: If each follows a plural antecedent, use a plural pronoun.

Unacceptable
They each sent in his application. Tom and Jerry each sent in
his application.
Acceptable
They each sent in their applications. Tom and Jerry each sent
in their applications.

Use a singular pronoun to refer to a collective noun acting as a

group.

Unacceptable
The astronaut selection committee submits their decision to
NASA.

Acceptable
The astronaut selection committee submits its decision to
NASA.

Use a plural pronoun to refer to the members of a collective

noun acting as individuals.

Unacceptable
The astronaut selection committee vote for its favorite
candidates.

Acceptable
The astronaut selection committee vote for their favorite
candidates.
Acceptable
The members of the astronaut selection committee vote for
their favorite candidates.
12
2007/2008 Dr B. Haddad
 Saleh Fareed

Verb Tense

Verb tense places an event in the present, the past, or the future.

Simple Present Tense

As an object approaches the speed of light, its mass rises.

Simple Past Tense

In 1887, Albert Michelson and Edward Morley compared the
speed of light in the direction of the earth's motion with that at
right angles to the earth's motion.

Future Tense
We will calculate our results to the nearest tenth.

Progressive Form ( the continuous form)

Use the progressive form in conjunction with any verb tense
(present, past, future, present perfect, past perfect, future
perfect) to express an action that is ongoing with respect to a
point in time or another action.
To make the progressive, use a form of the auxiliary be and the
present participle of the following verb.

In many sections of the United States, the productive topsoil is

rapidly disappearing. (futterung, Erde)
[present tense: the disappearing is ongoing with respect to the
present time]

In many sections of the United States, the productive topsoil was

rapidly disappearing.
[past tense: the disappearing was ongoing with respect to a
particular point in time]

13
2007/2008 Dr B. Haddad
 Saleh Fareed

Progressive Form ( the continuous form)

Although astronomers have been accumulating observations of

all the stages in a star's life in recent years, it is fair to say
that really tremendous strides have been taken within the past
few years in observing the very earliest stages of stellar life.
[present perfect: the accumulating was ongoing in the past and
continues to be ongoing in the present time] (mit riesnschritte, stern)

Do not use the progressive form with states or facts; use the
simple present tense or simple past tense instead. Some verbs
that commonly describe states: are appear, appreciate, be,
believe, belong, care, comprise, consider, contain, cost, desire,
dislike, doubt, entail, envy, fear, feel, forget, hate, have, hear,
imagine, include, know, like, look, love, mean, mind, need, owe,
own, possess, prefer, realize, recognize, remember, resemble,
see, seem, suppose, taste, think, trust, understand, want, and
weigh.

Unacceptable
When we compare what we can see of our Galaxy with other
galaxies, it is appearing that our Milky Way Galaxy is
resembling a spiral like many other galaxies, stoked with
hundreds of billions of stars unevenly interlaced throughout
chaotic swirls of interstellar gas and dust.

Acceptable
When we compare what we can see of our Galaxy with other
galaxies, it appears that our Milky Way Galaxy resembles a
spiral like many other galaxies, stoked with hundreds of billions
of stars unevenly interlaced throughout chaotic swirls of
interstellar gas and dust.
14
2007/2008 Dr B. Haddad
 Saleh Fareed

Punctuation and Mechanics

Use commas to set off transitional words and phrases,

introductory clauses, or introductory phrases to signal where
the introductory element finishes and the main part starts.

Transitional Words and Phrases

Place a comma after a transitional word or phrase that begins
a sentence

Moreover, the opening of an export market would help expand

the market for key escrow encryption.

In addition, several companies and individuals have proposed

commercial key escrow approaches.

Introductory Clauses
Place a comma after an introductory dependent clause.

Although key escrow is voluntary, critics say that the

introduction of Clipper points national policy in a disturbing
direction. (hinterlegen bei Treuhaendler)
Although keeping the same level is difficult , We believe standard is

Introductory Prepositional or Verbal Phrases

Normally, use a comma after an introductory prepositional or
verbal phrase. However, you may omit the comma after a short
introductory phrase if no ambiguity is possible.

For the first time, researchers have used DNA analysis to

identify the animal tissue in 4,000-year-old rock paintings.

Despite the error the experiment was successful.

Combining surface area with depth, we calculated the volume of

the pond.
15
2007/2008 Dr B. Haddad
 Saleh Fareed

Punctuation and Mechanics

Do not place a comma after an introductory participial or gerund

phrase if the phrase forms part of the subject or verb of the
sentence.

Combining surface area with depth was our principal method

for calculating the volume of the pond.

Coordinating Conjunctions Joining Independent Clauses

Place a comma before a coordinating conjunction that joins two

independent clauses. However, if the clauses are very short and
closely related, you may omit the comma.

Unacceptable
In almost all illicit markets, only the tip of the iceberg is visible
and there is no reason why the nuclear-materials black market
should be an exception. (unerlaubt)
Acceptable
In almost all illicit markets, only the tip of the iceberg is visible,
and there is no reason why the nuclear-materials black market
should be an exception.

16
2007/2008 Dr B. Haddad
 Saleh Fareed

Elements in a Series
Use a comma to separate items in a series.
Although placing a final comma before the coordinating
conjunction is often considered optional, omitting it can sometimes
cause confusion. Consequently, most scientific and technical
writing routinely uses a final comma in a series to prevent possible
ambiguities.

His intellectual acuity, diverse interests, frail physique, and

ethereal personality made Oppenheimer a man of legendary
proportions.

[In this sentence, omitting the final comma would not cause
confusion. Still, it is good practice in scientific and technical
writing to always include the final comma in a series.]

Weak
Contemporary physics is still exploring neutron stars, black holes
and the penetration of electrons through potential barriers.

[The omission of the final comma before and causes ambiguity:

are black holes and the penetration of electrons through potential
barriers specific topics connected to the general subject of
neutron stars, or are they separate items?]

Improved
Contemporary physics is still exploring neutron stars, black holes,
and the penetration of electrons through potential barriers.

17
2007/2008 Dr B. Haddad
 Saleh Fareed

Parenthetic Elements
Use commas to set off parenthetic elements.

Oppenheimer became known, of course, for leading the

physicists who built the atomic bomb at Los Alamos Laboratory.

18
2007/2008 Dr B. Haddad