Embed Size (px)
Citation preview
Welcome to
Writing Technical Documents
A l l i s o n H o r a k , I n s t r u c t o r
Please find
Chat and share
your favorite
author’s name.
Make sure
you have
some paper
and a pen
nearby.
Grab your
earbuds or a
headset for
the best
audio.
Chat
Ground Rules
Housekeeping
We’ll take a ten-minute break at the end of every hour.
Most of the time, you’ll be muted for a better audio experience for everyone.
Use the Chat feature to communicate with the group or with me directly.
Netiquette
Use clear and concise language.
Stick to the topic.
Avoid ALL CAPS.
Be cautious with humor and sarcasm.
Respect others’ opinions, even when they differ from your own.
Bottom left of your screen
If you don’t see it, move your cursor.
DefinitionTe c h n i c a l w r i t i n g i s w h e r e t h e a u t h o r i s d i r e c t i n g , i n s t r u c t i n g , o r e x p l a i n i n g s o m e t h i n g .
LearningObjectives
• Recognize the key features of
technical writing
• Understand and use plain
language
• Organize documents using a
logical flow
• Be consistent with technical terms
and punctuation
• Know the difference between
active and passive voice
…and more!
Let me hear from you!
One word:
What are the key
characteristics of technical
writing—when it’s done well?
Chat
• Concise
• Understandable
• Organized
• Designed
Examples of Technical Writing
Commodore 64 Online User Manual
When this program RUNs, it
displays a bouncing ball moving
across the screen from left to
right and back again. Take a
close look at the program to see how this is done.
Run the program and see what
happens now. Because you left
out the cursor control, each ball
remains on the screen until it is
erased by the ball moving right
to left in the second part of the program.
Done Well
Examples of Technical Writing
IRS Tax Form
Box a—Employee's social security
number. Enter the number shown on the
employee's social security card. If the
employee does not have a card, s/he
should apply for one by completing Form
SS-5, Application for a Social Security Card.
The SSA lets you verify employee names
and SSNs online. For information about
these free services, visit the Employer W-2
Filing Instructions & Information website
at www.socialsecurity.gov/employer. If you
have questions about using these services,
call 1-800-772-6270 (toll free) to speak
with an employer reporting technician at
the SSA.
Done Well
Guidelines for Technical Writing
1 . C l e a r
2 . C o n c i s e
3 . C o m p l e t e
4 . C o r r e c t
5 . C o u r t e o u s
5 Cs What readers value
1 . W h a t d o e s t h i s d o c u m e n t s a y?
2 . W h a t d o e s t h i s d o c u m e n t m e a n t o m e ?
3 . W h a t a m I s u p p o s e d t o d o a b o u t i t ?
3 Qs
What?
So
what?
Now
what?
What readers ask
What?
So what?
Now what?
Exercise
What?
So what?
Now what?
Exercise
What?
So what?
Now what?
What?
So what?
Now what?
What?
So what?
Now what?
Wo r d L e n g t h
Practical Tips
S e n t e n c e L e n g t h
Pa r a g r a p h L e n g t h
Always use the shortest, simplest word.
Keep your sentences to 25 words or fewer.
Have no more than six sentences.
Only cover one topic.
Less is more!
Word
Sentence
Paragraph
25
6 + 1
Exerciseshort
Plain Language
Plain Language Legislation
Plain Writing
Act of 2010
California
Government
Code §6219
Before
If evidence is not received before June 28, 2020, which is one year from the date of our first letter, benefits, if entitlement is established, cannot be paid before the date of receipt of the evidence.
After
We’ll have to turn down your claim if we don’t get your report by June 28.
Before
If you fail to comply with your duty of disclosure and we would not have entered into the contract on any terms if the failure had not occurred, we may void the contract within three years of entering into it. If your non-disclosure is fraudulent, we may void the contract at any time. Where we are entitled to void a contract of life insurance we may, within three years of entering into it, elect not to void it but to reduce the sum that you have been insured for in accordance with a formula that takes into account the premium that would have been payable if you had disclosed all relevant matters to us.
After
If you fail to disclose any relevant matter and we would not offer you insurance if this matter were known, we may within three years (1) void the contract or (2) reduce the sum for which you have been insured. If your nondisclosure is fraudulent, we may void the contract at any time.
FIELDTRIP!
Go to plainlanguage.gov
Click “Examples” at the top
Click the first link:
“Before and after”
Read at least three examples
(each one from a different
category); note what strategies
they used to meet plain
language standards
FIELDTRIP!
“ We a r e p r i s o n e r s of t h e n o t i o n t h a t a s i m p l e s t y l e r e f l e c t s a s i m p l e m i n d . A c t u a l l y , a s i m p l e s t y l e i s t h e r e s u l t o f h a r d w o r k a n d h a r d t h i n k i n g .”
William Zinsser
Big Word
terminate
Shorter Alternative
end
Simple Is Better
incombustible fireproof
utilize
substantiate
eliminate
regarding
Big Word
terminate
Shorter Alternative
end
Simple Is Better
incombustible fireproof
utilize use
substantiate prove
eliminate stop | end | remove
regarding about
Organizational Strategies
Order of
Importance
Chronological
Compare /
Contrast
General to
Specific
Simple to
Complex
Others?Let me hear
from you!
Specific to
General
Conclusion,
then
Supporting
Analysis
Geographic
Problem /
Solution
You supply
the after
Exercise:
Easy access to information and resources concerning
long-term care issues for seniors and the disabled
has been made available on a new website
developed by the County Department of Community
and Senior Services. To establish eligibility for a long-
term care voucher through the County Department
of Community and Senior Services, an applicant must
show, among other things, that the applicant has a
low income (according to state-defined thresholds)
and that the present housing of the applicant is substandard and inadequate.
Under the present circumstances, the budgetary
aspect is a factor that must be taken into consideration to a greater degree.
Active and Passive Voice
Tense = when
First, let’s clarify…
Voice = who
Active and Passive Voice
Voice = who
Voice = who
Passive voice:
The boy was bitten by the dog.
Active voice:
The dog bit the boy.
Method:
1. Find the verb.2. Who’s doing that?3. Does it appear first?
(If not, it’s passive.)
Active and Passive Voice
Switch to
active voice
Exercise:
All pay raises must be approved.
The project is being conducted by Personnel.
An investigation will be conducted into the complaint made by William McMasters.
Consistency
Exercise: Consistency
These mist eliminators are available
in diameters as large as 7 to eight
feet in diameter but are usually
limited to 36–48 diameter in sugar
refinery applications. The mesh pads
are usually 12 to sixteen cm thick. In
most sugar refinery installations,
they will eliminate B.O.D. and cut
production loss up to ninety-six
percent. As you know, BOD is caused
by decomposing organic matter in
wastewater streams.
Consistency
✓numbers
✓units of measure
✓grammar
✓symbols
✓capitalization
✓technical terms
✓abbreviations
✓punctuation
Consistency
✓punctuation
Period
Comma
DashEm dash ( — )
En dash ( – )
Hyphen (-)
A-GGoogle: practical
typography one space
H-MGoogle: Oxford comma
Maine dairy workers
N-ZGoogle: practical
typography hyphens and dashes
FIELDTRIP!
From this…
each and every
…to this
Omit Needless Words
postpone until later
brief in duration
Redundancies
From this…
each and every
…to this
Omit Needless Words
postpone until later
brief in duration
each | every | all
postpone
brief
Redundancies
From this…
each and every
…to this
Omit Needless Words
postpone until later
brief in duration
at a later date
in order to
at this point in time
Redundancies
Wordy Phrases
on most occasions
each | every | all
postpone
brief
From this…
each and every
…to this
Omit Needless Words
postpone until later
brief in duration
at a later date
in order to
at this point in time
Redundancies
Wordy Phrases
on most occasions
each | every | all
postpone
brief
later
to
now
usually
From this…
make a recommendation
…to this
Powerful Verbs
recommend
nominalization
From this…
make a recommendation
…to this
Powerful Verbs
reach an agreement
have a tendency to
recommend
agree
tend
nominalization
took action
make contact with
performed an audit of
made a statement
acted
contact
audited
stated
Positive Phrasing
Negative Phrasing
Tells the recipient what cannot be done
Has a subtle tone of blame
Includes words like can’t, won’t, unable to that tell the recipient what you can’t do
Doesn’t stress positive actions that would be appropriate, or positive consequences
Positive Phrasing
Tells the recipient what can be done
Suggests alternatives and choices available to the recipient
Sounds helpful and encouraging rather than bureaucratic
Stresses positive actions and positive consequences that can be anticipated
We can’t process your application…
… because you didn’t fill it out correctly.
We can process your application…
… when we receive a copy of your license.
- +
Three Positive Phrasing Strategies
1) If you can send us [whatever], we can complete the process for you.
2) One option open to you is [option].
3) We can help you to [whatever] if you can send us [whatever].
Negative Phrasing
We regret to inform you
that we cannot process
your application to
register your business
name, since you have
neglected to provide
sufficient information.
Please complete ALL
sections of the attached
form and return it to us.
Positive Phrasing
Congratulations on your
new business. To register
your business name, we
need some additional
information. If you return
the attached form, with
highlighted areas filled
in, we will be able to
send you your business
registration certificate
within two weeks. We
wish you success in your
new endeavor.
Compare and
Contrast
Negative Phrasing
We regret to inform you
that we cannot process
your application to
register your business
name, since you have
neglected to provide
sufficient information.
Please complete ALL
sections of the attached
form and return it to us.
Positive Phrasing
Congratulations on
your new business. To
register your business
name, we need some
additional information. If
you return the attached
form, with highlighted
areas filled in, we will be
able to send you your
business registration
certificate within two
weeks. We wish you
success in your new
endeavor.
Compare and
Contrast
FIELDTRIP!
Go to
allisonhorak.com
Click “Resources” at the top
Open and read the document
“Sample Abstract”
Complete these three sentences:
1. The main strength of this
document is…
2. One change that would improve
this document is…
3. The structure of this document is…
FIELDTRIP!
1. The main strength of this
document is…
2. One change that would improve
this document is…
3. The structure of this document is…
GraphicsBest practices
Always discuss the graphic before it appears.
Have at least one empty line above and below.
Intersperse graphics and text on the page.
GraphicsWhat are some other best practices?Come up with at least three.
FIELDTRIP!
Go to plainlanguage.gov
Click “Plain language guidelines”
at the top
On the left, click the sixth link:
“Design for reading”
On the left, click on the sub-heading
“Use tables to make complex material
easier to understand” and read that
whole section.
FIELDTRIP!
Come back to class with information
from your world that could benefit
from an if-then table
ActivityIdentify a work situation
or process you would
like to see improved or a
problem for which you
have a solution.
• Change procedure?
• New equipment?
• Cut costs?
• Improve morale?
Write to persuade your
boss to accept your
proposed improvement
or solution.
How it will workYou’ll be given 40 minutes
to write. (You’ll see the
timer on-screen.)
Then, you’ll go in breakout
rooms and read your drafts
aloud to each other.
Every person will get a:
(1) compliment
(2) suggestion for
improvement
Each group will have a:
• leader (decides who goes
next)
• timekeeper (everyone
gets five minutes to read
and get feedback)
Final
Exercise
W h a t h a v e w e c o v e r e d ?
Review
P l e a s e r e s p o n d t o t h e s e q u e s t i o n s i n C h a t :
Course Evaluation
1. What are one or two things you liked
about today’s course?
2. What’s a suggestion you have for
improving this course?
3. Thinking about your active engagement
during class: Was the amount—
• too little?
• just right?
• too much?
4. Yes or no—Did the exercises increase
your knowledge of this topic?
4
Thank you so much!
https://losriostraining.org/calhronline/
Resources
