1. The document provides tips for effective technical writing, including identifying goals and audience, structuring information well using headings and formatting, using examples and illustrations to clarify complex topics, keeping language concise and simple, using active voice, and avoiding ambiguity. 2. It also discusses writing requirements clearly and verifiably rather than focusing on design, and properly citing sources to avoid plagiarism.

1. Technical Writing
“Technical writing conveys specific
information about a technical subject to
a specific audience for a specific
purpose.”

2. Sources/Resources
Bugs in Writing, Lyn Depre
www.stc.org: Society for Technical
Communication
www.technical-writing-course.com:
A short course on technical writing
www.micron.com/k12/writing: Micron Writing in
the Workplace
www.critical-
reading.com/inference_denotation.htm:
Headlines

3. Technical vs Creative Writing
Technical Creative
Content factual, straight-
forward
imaginative, symbolic
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

4. The Challenge
Too often technical writing has a flat style
making documents difficult and tedious to
read.
There's no reason why technical writing
shouldn't be lively and interesting.
The real challenge is to express complex
ideas simply.

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

6. Tip 1: Identify your goals
Understand the type of technical report
you are writing.
 For example, 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?’

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

8. 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 …

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

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

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

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

13. 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%.

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

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

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

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

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

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

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

21. Writing tips specific to
Requirements
Not Design
Atomic
Verifiable
Achievable
More examples …

22. `
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.
-----------------------------------------------------------

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

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

25. 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 …

26. 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 …

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

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

29. 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]

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