TE C HN IC A L WR I TIN G

THIS ONE'S TOO SHORT. IT'S ALSO RUDE ("HELLO"? HOW ABOUT A NAME?). YOU SHOULD ALWAYS ASSUME WE'RE STILL
OFFERING THE POSITION, WRITE A QUICK NOTE, AND ATTACH YOUR RESUME.
This person tells us what they're incapable of. (For example, why point out that you're "average" at Excel?)
TECHNICAL WRITING

CONVEYS SPECIFIC INFORMATION ABOUT A

TECHNICAL SUBJECT TO A SPECIFIC AUDIENCE
FOR A SPECIFIC PURPOSE
TECHNICAL WRITING
WRITING THAT WORKS
 • TECHNICAL WRITING IS COMMUNICATION
WRITTEN FOR PRODUCTS AND SERVICES:
HOW TO MANUFACTURE THEM, MARKET
THEM, MANAGE THEM, DELIVER THEM, AND
USE THEM.

TECHNICAL
WRITING: A • TECHNICAL WRITING IS WRITTEN:
DEFINITION • IN THE WORK ENVIRONMENT (IN THE
OFFICE, FROM 8:00 TO 5:00, NOT
COUNTING OVERTIME)

• FOR SUPERVISORS, COLLEAGUES,

SUBORDINATES, VENDORS, AND
CUSTOMERS
TECHNICAL WRITING, WHICH MUST BE UNDERSTOOD EASILY AND
QUICKLY, INCLUDES:

brochures
memos and e-
letters reports instructions and
mail
newsletters

PowerPoint
the job search web pages fliers graphics
presentations
 TECHNICAL WRITING: A DEFINITION

• TECHNICAL WRITING IS NOT LITERATURE; IT’S NEITHER PROSE

WHICH RECOUNTS THE FICTIONAL TALES OF CHARACTERS NOR
POETRY WHICH EXPRESSES DEEPLY FELT, UNIVERSAL EMOTIONS
THROUGH SIMILES AND METAPHORS.

• TECHNICAL WRITING IS NEITHER AN EXPRESSIVE ESSAY NARRATING

AN OCCURRENCE NOR AN EXPOSITORY ESSAY ANALYZING A TOPIC.
• TECHNICAL WRITING IS NOT JOURNALISM, WRITTEN TO REPORT THE
NEWS.

• TECHNICAL WRITING DOES NOT FOCUS ON POETIC IMAGES, DESCRIBE

PERSONAL EXPERIENCES, OR REPORT WHO WON THE BASKETBALL GAME.

TECHNICAL WRITING: A DEFINITION

 INSTEAD, TECHNICAL WRITING IS:
—AN INSTRUCTIONAL MANUAL FOR

TECHNICAL REPAIRING MACHINERY

WRITING: A —A MEMO LISTING MEETING AGENDAS

DEFINITION —A LETTER FROM A VENDOR TO A

CLIENT
—A RECOMMENDATION REPORT
PROPOSING A NEW COMPUTER SYSTEM
COMPARISON/CONTRAST: TECHNICAL WRITING VS. ESSAYS
Components Technical Writing Essays Summary
Development Uses examples, Uses examples, Same for both
anecdotes, anecdotes,
testimony, data, research testimony, data,
research
Grammar It is important It is important Same for both

Organization -Provides an introduction, Provides an Similar in some

body, and conclusion introduction, ways, different in
-Uses a subject line vs. a thesis statement, Others
thesis and itemization of body paragraphs,
points vs. transitional transitional words,
words and topic sentences
-Uses topic sentences
only when needed,
dependent upon the type
and length of
correspondence
 COMPARISON/CONTRAST: TECHNICAL WRITING VS. ESSAYS
Components Technical Writing Essays Summary

Style Uses short, denotative Uses longer, Different

words; short sentences; connotative words;
and short paragraphs longer sentences;
and longer
paragraphs
Document Uses highlighting Not usually a Different
Design techniques, factor
such as graphics,
headings,
subheadings, various
fonts,
white space, bullets, etc.
TECHNICAL VS CREATIVE WRITING
Technical Creative
Content factual, straight- imaginative, symbolic
forward

Audience specific general

Purpose inform, instruct entertain, provoke,

inspire

Style formal, standard informal, artistic

Tone objective subjective

Vocabulary specialized general, evocative

Organization sequential, systematic arbitrary, artistic

People read literature for pleasure,
essays for
enlightenment, and journalism for
news.
People read technical writing to
accomplish a job.
Characteristics of
Effective Technical Writing
 Clear—is easily understood by the intended audience
without ambiguities.
 Accurate—is factual, correct, free from bias.
 Correct—follows both grammatical and technical
conventions.
 Comprehensive—contains all necessary information.
 Concise—is clear and complete without excess or
redundant verbiage.
 Accessible—includes headings and subheads, indexes,
and table of contents.
Tip 1: Identify your goals
 Understand the type of technical report you are
writing.
 Forexample, the following demand different approaches:
concept proposal, requirements specification, user guide

 Write down your specific aim

 Ask yourself ‘why am I writing’ and ‘what am I trying to
achieve?’
Tip 2: Know your audience
 Match your content to your readers’ knowledge.
 If you are in doubt, aim for the simpler approach.
 If appropriate, include several alternate levels of info.
 Define your terms.
 computer terminology fluid
 if many terms need definition, use a glossary
With technical writing you must present your information so
readers can:
extract the main points without necessarily reading the
whole
easily find information that interests them
quickly absorb crucial information

Therefore …
Tip 3: Structure well
 Make use of headings and sub-headings, with a
consistent numbering scheme.
 Do not refer to information by reference number alone.
 Itemize facts wherever possible.
 Use textual highlighting for emphasis (italics, underlining,
boldface).
For example
It is important to structure your document well. You should
make use of headings and sub-headings, with a consistent
numbering scheme. Remember not to refer to information
by reference number alone. Additionally it is important to
itemize facts wherever possible. Finally, you can sometimes
use textual highlighting for emphasis (italics, underlining,
boldface).
For example
You should structure your document well:
 Make use of headings and sub-headings, with a
consistent numbering scheme.
 Do not refer to information by reference number alone.
 Itemize facts wherever possible.
 Use textual highlighting for emphasis (italics,
underlining, boldface).
Tip 4: Clarify and Illustrate
 Use examples (scenarios)
 Use illustrations, diagrams
 Use flowcharts, graphs, tables
----------------------------------------------------------
 If a description is complex, repeat it using a different
approach
Tip 5: KISS (short and simple)
 Avoid long sentences that present several facts.
-----------------------------------------------------------
If the sales for the current month are below the target sales, then a
report is to be printed, unless the difference between the target
sales and actual sales is less than half of the difference between
target sales and actual sales in the previous month, or if the
difference between target sales and actual sales for the current
month is under 5%.
Compare
(One Sentence—70 words)
A highlight of the web site is the development of two types
of electronic advisory systems—Expert and Technical
where both of the systems inform the user about standards
by either asking a series of questions which determine
whether, how, and which specific parts of the standard
apply to the user's activities, or addressing complex
standards by placing in one location a large amount of
information about the standard.
------------------------------------------------------------------
(Three sentences—Total 42 words)
The web site offers both expert and technical advice
sections. These explain standards by asking questions to
find out if and how the standards apply to the user. They
also address complex standards by placing all the relevant
information in one place.
Tip 5: KISS
Omit needless words and information
----------------------------------------------------------
It is very important that every single generated error message, no matter how minor of an error,
be carefully recorded by the Foobar system in the audit file for future consideration by the
maintenance engineers who will try to improve the system’s reliability.

It is very important that every single generated error message, no matter how minor of an error,
be carefully recorded by the Foobar system in the audit file for future consideration by the
maintenance engineers who will try to improve the system’s reliability.

----------------------------------------------------------
Foobar must record every generated error message in the audit file.
Tip 5: KISS
Use simple words rather than complex ones
-----------------------------------------------------------
As we noted in the preceding section, if you purchased additional
printer options, such as a second printer tray, it is a requirement
you verify its correct installation.
-----------------------------------------------------------
As we noted in the previous section, if you bought extra printer
equipment, such as a second printer tray, you must check that you
installed it correctly.
Tip 6: Use Active Voice
Passive verbs are longwinded, ambiguous and dull. Active
verbs make your writing simpler, less awkward, clearer and
more precise.
----------------------------------------------------------
The QMS Magicolor 2 Printer is equipped with two
interfaces, one is known as the parallel interface, the other
is known as the Ethernet interface. Whatever interface
connection is needed, you will find that MS Windows 98
has already been preinstalled and your software
applications are based on this platform.
-----------------------------------------------------------
The QMS Magicolor 2 Printer has Parallel and Ethernet
interfaces. Whatever interface you need, you will find your
software applications will work on the preinstalled MS
Windows 98.
You show the agent actively
Passive: When memory is so short that it cannot be freed
sufficiently fast to satisfy demand, swapping can be used.

Active: When the operating system becomes so short of

memory that the paging process cannot free memory
sufficiently fast to satisfy demand, it can use swapping.
Tip 7: Avoid Ambiguity
Actual Headlines:
 Drunk Gets Nine Months in Violin Case
 Kids Make Nutritious Snacks
 New Vaccine May Contain Rabies
 New Study of Obesity Looks for Larger Test
Group
 Police Begin Campaign to Run Down
Jaywalkers
 Red Tape Holds Up New Bridge
 Local High School Dropouts Cut in Half
Summation
1. Identify your goals
2. Know your audience
3. Structure well
4. Clarify and illustrate
5. KISS
6. Use Active voice
7. Avoid ambiguity
Writing tips specific to Requirements

 Not Design
 Atomic
 Verifiable
 Achievable

More examples …
`
All error messages must be helpful
-----------------------------------------------------------
Every registered user must have a unique
UserID that will be used as a key field in a
database table.
-----------------------------------------------------------
The control total is taken from the last
record.
-----------------------------------------------------------
Req 5.2.3: The Word Search puzzle area must be
rectangular in shape and no more than 60
characters wide.
-----------------------------------------------------------
The output should usually be presented on the
screen within 10 seconds of the user pressing the
Enter Key.
-----------------------------------------------------------
Using the set of words, the system will generate a
crossword puzzle within 2 seconds.
-----------------------------------------------------------
When an error message is generated about
the sales data, it should be dumped to the
audit file.
----------------------------------------------------------
If the user is experience level 2, or has root
access, then accept the amount provided as
input and print the accepted message;
otherwise, if the experience level is 1, then
print message 1.
Citation of Sources
How? There are many styles, all easily
accessible.

When?
See our graduate Independent Study page:
www.csc.villanova.edu:8080/academics/gradIS

Don’t plagiarize: Consider …

Plagiarism Example:
Suppose a journal article begins:

“A classic problem in concurrent programming is that of the ‘dining

philosophers’ which challenges the power of any aspiring
concurrent program language. Recently, a growing number of
logic programming languages have been refined to handle
concurrent programming; one in particular is Parlog86.”

You are to write a report about the article …

Blatant Plagiarism - Illegal:
Suppose a journal article begins:
“A classic problem in concurrent programming is that of the ‘dining
philosophers’ which challenges the power of any aspiring
concurrent program language. Recently, a growing number of
logic programming languages have been refined to handle
concurrent programming; one in particular is Parlog86.”

The paper Parlog86 and the Dining Logicians revolves around a

classic problem in concurrent programming, the ‘dining
philosophers’ problem, which challenges the power of any aspiring
concurrent program language. Recently, a growing number of
logic programming languages have been refined to handle
concurrent programming, including Parlog86.
Even this is plagiarism:
Suppose a journal article begins:
“A classic problem in concurrent programming is that of the ‘dining
philosophers’ which challenges the power of any aspiring
concurrent program language. Recently, a growing number of
logic programming languages have been refined to handle
concurrent programming; one in particular is Parlog86.”

The paper Parlog86 and the Dining Logicians revolves around a

problem in concurrent programming, the ‘dining philosophers’
problem. Any aspiring concurrent program language is
challenged by the power of this classic problem. In recent times,
an increasing number of logic programming languages have
been revised to handle concurrent programming, including
Parlog86.
Here’s a legal approach, but its not very good:
Suppose a journal article begins:
“A classic problem in concurrent programming is that of the ‘dining
philosophers’ which challenges the power of any aspiring
concurrent program language. Recently, a growing number of
logic programming languages have been refined to handle
concurrent programming; one in particular is Parlog86.”

The paper Parlog86 and the Dining Logicians revolves around a

classic problem in concurrent programming, the ‘dining
philosophers’ problem. The paper says the problem “challenges
the power of any aspiring concurrent program language.” As noted
in the same paper “recently, a growing number of logic
programming languages have been refined to handle concurrent
programming, including Parlog86.” [Ringwood 1988]
Best is to use your own words:
Suppose a journal article begins:
“A classic problem in concurrent programming is that of the ‘dining
philosophers’ which challenges the power of any aspiring
concurrent program language. Recently, a growing number of
logic programming languages have been refined to handle
concurrent programming; one in particular is Parlog86.”

In our Operating Systems class, we studied the “dining

philosophers” problem. This problem uses philosophers and chop
sticks to represent computer processes and resources, and
models common resource contention problems. A good test of a
concurrent programming language is to see how it does in solving
this problem. That is what is done with Parlog86, a logic
programming language, in the paper Parlog86 and the Dining
Logicians.