Subido por John Diego

Technical Writing Fundamentals

Technical Writing
Presented by Elizabeth Hardin
University of Alabama in Huntsville
This webinar will cover
Introduction: What is technical writing?
Key Concepts: Understanding your audience and purpose
Planning and organizing your document
Drafting your document
Using plain language
Revising and editing your document
Reviewing grammar and punctuation
When you have questions
● Between each section of this presentation, I will answer relevant
● There will also be time at the end of this presentation for questions.
What is technical writing?
● Technical writing, or technical communication, is the use of words and
images to explain complex concepts in ways that people can
● It can be written (like a software user manual) or presented (like a video
tutorial that demonstrates a process).
● It relies on words and images to help an audience understand a
technical concept or complete a task.
● Every document has its own audience (who will read it?) and purpose
(why will they read it?).
Key Concepts:
Audience and Purpose
Audience means the people who are reading and using your document.
● Analyze your audience
○ While the audience for your academic writing so far has probably been your instructor,
the audience for documents technical writing is different and varied.
Understand the audience’s needs and expectations.
Consider primary and secondary audiences
● If audiences other than your primary one will read your document,
consider ways to make it appropriate for multiple audiences.
● Make your document modular (break it up into components for multiple
● Examples: “admin” and “general user” sections or including an
executive summary for people who don’t need the technical details.
● Your responsibility is to help the reader understand the information
● The content is technical and complex; it’s our job to communicate it
effectively, without the audience having to do extra mental work.
● If they’re thinking too hard about how you’ve presented your
information or what you mean, they’re not thinking about the content.
● No one wants to read what you write. They must read it to do their jobs.
● What is the audience going to DO with your document?
● What do you want the audience to do with this information?
For example,
● Are they trying to get enough information about your project so they
can approve it?
● Do they need help assembling a table from IKEA?
Most of the writing technical writers do falls into two categories:
1. To help others learn about a subject, carry out a task, or make a decision.
● If you’re writing a proposal, your document’s purpose is to help the
reader make their decision about who to hire or what project to fund
(hopefully yours!)
● If you’re writing software user help, your document’s purpose is to help
someone achieve a goal with the software.
2. To encourage others to take action.
● An electric car company might describe their vehicles’ specifications
and benefits to encourage customers to buy their product.
● Genre means the type of document you create.
● The genre dictates the document’s structure and delivery.
● Examples:
○ Technical report
○ Blog post
○ Memo
The Writing Process:
Planning, Drafting, Editing,
Revising, and Proofreading
The planning process
Analyze your audience and purpose
Generate ideas
Organize and outline your document
● Determine the structure and content of your document.
● Some of the structure and content is determined by genre.
For this challenge, your audience and purpose of your documents are set
for you.
You are writing two reports (and presentations) that have specific
requirements laid out in the program guidebook.
● Design Review
● Operational Readiness Review
● Design Review
○ Audience: management or customers
○ Purpose: to prove to management or customers that your team has considered all
factors and reasonable design options and that your design meets all requirements for
the project
● Operational Readiness Review
○ Audience: management or customers
○ Purpose: to prove to management or customers that your product is ready to complete
the mission.
Planning: Methods of development
Problem -> Method -> Solution
● Describing the problem to be solved and then your approach to solving
This is the most common organization for technical reports and design
reports, and the one you’ll use as you report your team’s solutions to the
Planning: Methods of development
Choosing a method of development helps you organize and present your
information in a logical way.
For example, some methods are
● Chronological (describing something in the order it happened or will
● Spatial (describing the physical structure of something)
● General to specific (explaining a broader idea or context and then
focusing on a specific, complex idea)
● Problem -> Method -> Solution (describing the problem to be solved
and then your approach to solving it)
Planning: Document organization
The major sections of the reports are provided for you, as described in the
HERC Guidebook. For example, for the Design Review Report, you must
Cover Page
Vehicle Criteria
Task and Other Mission Components
Mission Performance Predictions
Project Plan
You can start outlining your draft with these major sections as headings.
Planning: Document organization
Executive summary
● Most formal reports include this section, which is an overview that
provides the reader with the report’s main points and results.
● It should be standalone, meaning that a reader who doesn’t need to
know the details can understand the major points of the report.
● It’s similar to an abstract.
Planning: Document organization
Executive summary
● For a 10-page report, between 100-150 words should be enough.
● Include it in the report after the cover page, and label it (use a section
header like “Abstract” or “Executive Summary”).
● Write it last.
● Once you know your major topics and have an outline, start writing.
● Start with the easy stuff. Make notes about what to fill in.
● Drafts are fluid, not written in stone. Be flexible and willing to adapt and
change when you can.
Document Design
Drafting: Working with style guides and
Many elements of your reports’ style are dictated by the HERC guidebook.
● For example: “The Design Review and Operational Readiness Review
reports shall be in Arial, size 12 font on 8.5 x 11 paper with 1 inch
● Each report shall include the team name and report title on the cover
page. All pages shall be numbered.
● Reports shall not exceed the page limit. Any additional pages will not
be scored.”
Drafting: Document and page design tips
● Organize your report with section headings and subheadings.
● These document design features help the audience understand how
your ideas are organized.
● Keep fonts and font sizes consistent.
○ Unless directed otherwise, if your body text is size 12 pt., 14 pt. bold font is good for
headings. Subheadings can be 12 pt. ALL CAPS.
Caption figures and title tables with 11 pt. font.
Drafting: Document and page design tips
● Use single or 1.15 spacing.
● Don’t indent first lines of paragraphs.
● Use a line break (a blank line) between paragraphs and before and
after headers.
● If a section heading can fit on the bottom of a page, but its content
can’t, start the section on a new page.
Drafting: Visuals
● For your reports for this project, you will include your graphics in an
● Make sure to give all graphics a title or caption so you can refer to them
in the text.
● Title tables above the table (Table 1: Costs of materials).
● Caption figures below the image (Figure 1: Wheel design).
○ Tables and figures are numbered independently. You can have both Table 1 and
Figure 1 in your report.
● Use these titles and captions to refer to the visuals in the text.
○ As shown in Figure 1…
○ Table 1 shows…
Tone and Word Choice
Tone and word choice
Formal vs. informal
● Documents like reports are usually formal, but don’t let “formal” mean
“overly complex.” Use plain language and straightforward construction
(more about that soon).
● More formal writing may require you to use passive construction (more
about that next) and third person (no “I” or “we”).
Tone and word choice
Passive vs. active construction
● Passive: The temperature of the environment was considered.
● Active: Our team considered the temperature of the environment.
Formal reports often use passive construction. This emphasizes the work
that was done or the findings of a test instead of who did the work.
Tone and word choice
Verb tenses: consider the document’s purpose. Keep it consistent.
Use future tense for planning documents and proposals.
● The vehicle will be tested for stability.
Use past tense for reports about things that have been done (test reports,
for example).
● The vehicle was tested for stability.
Precise language
● When you describe something, use precise, verifiable language.
○ Instead of “multiple holes were drilled in the plank,” write “three 1” holes, 2’ apart, were
drilled into the plank.”
● Avoid subjective statements. When evaluating something, include
quantifiers or include the criterion you used to evaluate.
○ Instead of “this design was best,” write “this design completed the test successfully
and was 2 pounds lighter than the other options.”
● One paragraph = one idea.
● Use clear topic sentences to alert your reader to what the paragraph is
● Use transition words and phrases (however, next, then, as a result...) to
help the reader understand connections between paragraphs.
● Avoid very long paragraphs.
○ There’s no rule about exactly how long a paragraph should be. If you notice
paragraphs that are ½ a page to one page long, read them carefully to figure out
where you’re transitioning to a new idea and break the paragraph in logical
Using Plain Language
Plain Language and Clarity
A goal of professional communication is to be clear and precise so readers
can easily understand the message.
Plain Language
● It’s the law.
● It’s an ethical issue.
● The Plain Writing Act of 2010 requires all organizations to make sure
their writing helps readers
○ Find what they need
○ Understand what they find
○ Use what they find to meet their needs
● Government guidelines here.
Plain Language
Watch out for jargon
● Every field has its specialized language.
● If the audience (the reader or user) speaks the same “language,” it’s ok
to use it.
● But remember that you’re writing for the user. If they aren’t likely to
know a technical term, use a word they know.
Plain Language
● Acronyms—spell them out the first time you use them.
● Example:
○ First time: Computer-based training (CBT).
○ Subsequent times: CBT
● Note: Keep punctuation consistent (choose either C.B.T. or CBT).
Plain Language
Watch out for redundant words
● Absolutely complete
● Refer back
● End result
● Final outcome
● Reduce down
Common wordy phrases and their
concise equivalents
In the event that
Until such time as
Have the capability of
At this point in time
Due to the fact that
With reference to
Prior to the start of
Plain Language
Watch out for “hidden” verbs or unnecessary nominalization.
“Apply for the program” is clearer than
“Make an application for the program.”
“The officer investigated the claim” is clearer than
“The officer performed an investigation on the claim.”
Plain Language
Tip: Read your writing out loud. If it sounds wordy or awkwardly phrased, it’s
also wordy and awkward in writing.
Plain Language Revision
Make this sentence more concise:
We remain in communication with our sales staff on a daily basis.
Plain Language Revision
Make this sentence more concise:
We remain in communication with our sales staff on a daily basis.
We talk to our sales staff every day.
Plain Language Revision
Make this sentence more concise:
For all intents and purposes, our company’s long-term success depends to
a certain degree on various factors that are in general difficult to foresee.
Plain Language Revision
Make this sentence more concise:
For all intents and purposes, our company’s long-term success depends
to a certain degree on various factors that are in general difficult to
Our company’s success is uncertain.
● After you have a draft, revise it.
● Revision = re-vision (seeing again)
● You’re not writing in stone--if something needs to change, change it!
● Go back and read your document carefully to make sure you have
communicated what you need to.
● Remind yourself of your audience and purpose. Has your
understanding of the subject, audience, or purpose changed?
● If your template or requirements allow you to, you can change the order
of sections to ensure that you have a logical flow.
● Write the introduction (or abstract or executive summary) last, when
you have the most knowledge of the document.
● The abstract or executive summary needs to follow the same order of
the document, so don’t change up your document and then forget to
update the abstract.
Editing means checking your revised draft to improve your writing.
Mechanics (use of numbers and abbreviations)
Word choice and diction
Editing for consistency
● Keep abbreviations consistent (capitalization, punctuation)
● Write terms consistently (don’t write meters in one place and metres in
Editing for word choice
● Don’t try to vary your writing for interest, like you might do in an
academic writing or fiction writing.
● For example, in instructions for computer software, if you use the verb
“select” to mean clicking a button, use “select” every time to describe
that action.
Grammar and
Grammar and Punctuation
Review: Common Errors
Comma use
Other problematic punctuation
Fused sentences and comma splices
Commonly confused words
Proper plurals
Parallel structure
Commas after introductory
Include a comma after introductory elements of any length.
● Between 40 and 50 degrees west and just south of 10 degrees north in
the western end of the doldrums belt, calms do occur with frequency,
and hurricanes originate there with great frequency.
● Today, the computer consortium of IBM, Motorola, and Apple is
announcing its new PowerPC chip.
Unnecessary commas
INCORRECT: The separator between black mix and the zinc electrode,
consists of a paper barrier coated with cereal or methyl cellulose.
Compound sentences
Include a comma after a coordinating conjunction (for, and, nor, but, or, yet,
so—use the mnemonic FANBOYS)
● The younger students are computer literate, so we will not teach basic
computer skills.
Compound predicates
This is when the subject is doing two things in the “verb” part of the
No comma needed.
● Inspectors must enter their name in the record book and lock the
Series elements
● I support the Oxford comma (the comma after the final element in a
● There is some debate about it, but using it can reduce confusion and
make writing clearer.
● My book includes quotes from my parents, the president and the vice
● My book includes quotes from my parents, the president, and the vice
Used to connect two independent clauses (clauses that can stand alone as
sentences) not linked by a coordinating conjunction (for, and, nor, but, or,
yet, so).
● The older interface was less user friendly; research shows users prefer
the updated version.
● The older interface was less user friendly, and research shows users
prefer the updated version.
Use a semicolon when using ”however” to join independent clauses.
● Usability research showed that users over 40 prefer the older UI;
however, younger users like the new version.
Can also be a “supercomma,” to separate items in a series that already
contains commas.
● The HOA meeting was attended by three elected officials: James
Peterson, HOA president; Michelle North, HOA vice president; and
Harry Albert, recording secretary.
Used to indicate possession.
The report’s contents (singular possessive)
Charles’s colleague (singular possessive)
The documents’ pages (plural possessive)
Children’s toys (plural possessive)
Don’t be fooled by words that look and sound plural, but aren’t, like lens or
I lost one contact lens.
I lost both of my contact lenses.
My right contact lens’s prescription seems wrong.
My contact lenses’ filthy condition appalled my eye doctor.
Apostrophes: Compound
Add 's to the end of the last noun to show joint possession of an object
● Ann and Tom’s house
● Amanda, Jill, Alice, and Sejal’s lunch
Apostrophes: Compound
Add 's to the end of the both nouns to show possession of different objects
● Ann’s and Maggie’s houses
Possessive pronouns
The pronominal possessives hers, its, theirs, and yours have no
● The house is ours.
● He is a friend of yours.
● The granite countertop has lost its shine.
○ Don’t let spellcheck talk you into the wrong “its” in this case.
Not used to create plural nouns.
● INCORRECT: The graphic’s in this application are cutting edge.
● CORRECT: The graphics in this application are cutting edge.
Watch out for words that look “weird” when they’re made plural. They might
have an unexpected plural form, or they might just be correct with an “s.”
● Vertexs (?) Vertex’s (?) NO!
○ Vertices
● Memo… memos (?) YES!
Proper plurals
Watch out for words whose plural forms are hard to say. They still need an
“s” to make them plural in writing.
● Used to introduce a word, phrase, or clause that amplifies, illustrates,
or explains a general statement.
○ In our report, we compare three elements of the elevators: speed, safety, and
passenger capacity.
● The text preceding the colon should be able to stand alone as a
complete sentence, without the list.
○ INCORRECT: In our elevator report, we compare: speed, safety, and passenger
Hyphenate compound adjectives when they come before the word they
modify (but not when they come after).
● start-up costs
● salt-free crackers
● These crackers are salt free.
There is no need to hyphenate modifiers constructed from an adverb and an
● Newly built airport
● Recently acquired evidence
Fused sentences, comma splices,
and run-on sentences
● Run on sentences are not simply sentences that are too long.
● They contain two or more independent clauses that aren’t connected
● Incorrect connections include
● No connecting punctuation at all
● A comma
● A coordinating adverb (like however, therefore, furthermore…)
Fused sentences, comma splices,
and run-on sentences
● All of our reports are peer reviewed, our colleagues proofread for
grammar and clarity.
● I emailed the report to my boss, however she ignored it.
● Every inspector is expected to file a separate report there are no
(These are ALL run-on sentences.)
Fused sentences, comma splices,
and run-on sentences
Corrected sentences
● All of our reports are peer reviewed. Our colleagues proofread for
grammar and clarity.
● I emailed the report to my boss; however, she ignored it.
● Every inspector is expected to file a separate report, and there are no
Objective pronouns
A pronoun that stands for the person or thing receiving the action of the
verb or following a preposition.
CORRECT: Mr. Jones hired Robert and me.
INCORRECT: Mr. Jones hired Robert and I.
Tip: Cross out “Robert and” and see how the sentence sounds.
Subjective pronouns
A pronoun that is used as the subject of a clause or sentence.
CORRECT: Robert and I interviewed for the same position.
Subject-verb agreement
Even if the subject is far away from the verb, make sure they agree.
The documents, which are outdated and ready to be updated by the writing
team, are stored on the server.
Subject-verb agreement:
There is versus there are
Use there are when the actual subject is plural.
Use there is when the actual subject is singular.
● There are numerous errors in this document.
○ Numerous errors are in this document.
● There is a spelling mistake on page 5.
○ A spelling mistake is on page 5.
Parallel structure
A sentence (or list) is parallel if its coordinate elements follow the same
grammatical form.
Lists that are parallel are much easier for the reader to understand.
Parallel structure
Not parallel: The manager was bombarded with phone calls, sent several
emails, and had everyone coming to visit her.
Parallel: The manager was bombarded with phone calls, sent several
emails, and visited by everyone.
Not parallel: The hardest parts of his job were giving presentations and to
write reports.
Parallel: The hardest parts of his job were giving presentations and writing
Parallel structure in lists
Software analyst
May 2017 – August 2019
● Developed web applications using Java.
● Designing UI for online bill-paying application.
● Have written automated tests in collaboration with the QA team.
How can we improve this list?
Parallel structure in lists
Software analyst
May 2017 – August 2019
● Developed web applications using Java.
● Designed UI for online bill-paying application.
● Collaborated with the QA team to write automated tests.
Trustworthy grammar sites
● The OWL (Online Writing Lab) at Purdue
○ General Writing Resources > Grammar
The Center for Writing Studies at the University of Illinois
● Check for missing or repeated words.
● Reading your writing aloud can help you find errors like this.
● Check your capitalization--don’t capitalize for emphasis, but make sure
to capitalize proper nouns (names of software and other products,
names of cities and countries, for example).
● Review your page design (including headings and subheadings).
● Double check margins, font size, and other design requirements.
Commonly confused words
Check carefully for homophones
their, they’re, there
to, too
vary, very
summery, summary
whether, weather
Commonly confused words
and check for words that are similar and commonly confused
loose, lose
affect and effect (Affect is the verb. Effect is the noun)
Its (plural possessive of it—The cat washed its tail.)
It’s (contraction of it is—It’s a very fluffy tail.)
Your spell check software can do a lot, but YOUR brain can do better.
Remember to...
Plan and outline your document first.
Use plain language and straightforward sentence construction.
Keep page design, style, tone, and language consistent.
Revise, edit, and proofread.
Good technical writing resources
Open Technical Communication (free digital textbook)
Purdue OWL (Online Writing Lab): Writing in Engineering
The Mayfield Handbook of Scientific and Technical Writing