Technical Writing Workshop
Presented by
John Cole
The University of Texas at Dallas
May 21, 2015
Technical Writing
1
Instructor: John Cole
• Completed MS in Computer Science from Illinois
Institute of Technology
• 40 years of writing software in a large variety of
industries
• Wrote my own software documentation
• Technical editor for Discover Visual Cafe
• 6 years as an adjunct (part-time) faculty member
at UTD from January 2006 through May 2012, full
time since then. Also taught at Collin College and,
long ago, IIT
Technical Writing
2
Course Objectives
• To introduce you to technical writing
• To make you a better writer in all areas
Technical Writing
3
Programming and Writing
• “Everyone in this country should learn how to
program a computer… because it teaches you
how to think.” -Steve Jobs
• Programming is necessarily precise, clear, and
accurate. So is good technical writing.
Technical Writing
4
Course Outline
• What is technical writing?
• Components of writing.
– Development
– Grammar
– Organization
– Style
– Document Design
Technical Writing
5
Course Outline, Continued
• Traits of technical writing:
– Clarity
– Conciseness
– Accessible document design
– Audience recognition
– Accuracy
• Applications
Technical Writing
6
What is Technical Writing?
• Technical writing is communication written for
and about business and industry, focusing on
products and services: how to manufacture
them, market them, manage them, deliver
them, and use them.
• It is denotative, not connotative. That is, it
conveys precise information. “Just the facts,
ma’am.”
Technical Writing
7
What Technical Writing Is Not
• Literature. It is not a story nor poetry.
• Journalism. It does not narrate an event nor
report news.
• An essay. It does not express an opinion.
• Personal. While it may relate to the reader, it
is not about your experiences.
Technical Writing
8
Technical Writing
• None of this means it cannot be creative and
sometimes even fun, but that is not its
purpose
• Consider: “Imagine a container that can hold a
mixture of solid, liquid, and gas, and can let
the gas out through a hole in the bottom.”
Technical Writing
9
Exercise
• Take 5 to 10 minutes to write a paragraph
explaining why you decided to take this
workshop
Technical Writing
10
Why Learn it?
• Communication skills are essential. The best
idea in the world is worthless unless you can
communicate it
• Written communication is how ideas are
preserved
• Nearly any job you get, no matter how
technical, will require writing
Technical Writing
11
Examples of Technical Documents
•
•
•
•
•
•
•
•
•
Software manuals
Company Web sites
Your resume
Instructions that come with a device
A description of how you built something
A bread recipe
Help files
This presentation
Some e-mails
Technical Writing
12
Writing in Computer Science
•
•
•
•
•
Program specifications
Project plans
Use cases
Comments in the code
Research papers
Technical Writing
13
Five Components of Writing
•
•
•
•
•
Development
Grammar
Organization
Style
Document Design
Technical Writing
14
Development
• Uses examples, anecdotes, testimony, data,
research
• Start with overall objectives, then get into
details
• Logical progression
Technical Writing
15
Development
• For example, this is your overall objective:
To assemble your robot chassis, you will need a
Phillips screwdriver. Remove the parts from the
package and make sure you have the following
items: (the items are listed.)
• Now you can get to specifics, such as:
Attach the motor to the motor mount using the
machine screws, as shown in the diagram
Technical Writing
16
Development
• Research often includes looking up
information from various sources
• In computer science, it can involve looking at
source code to determine what it really does
• Always keep track of your sources
Technical Writing
17
Development
• Presentation of data is crucial
• Use paragraphs, but also charts, graphs, and
tables
Technical Writing
18
Grammar
• Always use correct grammar and spelling
• If you’re not sure, look it up or get help from
someone who knows.
• UTD has a writing center staffed with people
who will be glad to help
Technical Writing
19
Grammar
• Use second person; talk directly to your
reader
• Avoid slang
• Don’t be, like, real informal
• Explain acronyms. What is a CCN? There are
many possible meanings for most TLAs.
Technical Writing
20
Grammar
• If your word processor puts a wavy red line
under a word, there is probably something
wrong
• Don’t shift tenses in the middle of a sentence
• A sentence has a subject and a predicate
• Don’t run your sentences together this makes
them hard to understand
• Make the antecedents of your pronouns clear
Technical Writing
21
Grammar
• Use correct punctuation: Periods end
sentences and commas separate dependent
clauses
• Periods go inside quotation marks and
parentheses
• Avoid semicolons in technical writing; they can
make it too complex
Technical Writing
22
Grammar
• Apostrophes are not used to form a plural:
“You will need four 2N3909 transistor’s.”
Worst example: “Altex Electronic’s”
• Apostrophes are used for contractions and
possessives:
• Difficult case: its and it’s
• U r not txting lol
Technical Writing
23
Grammar
Eye halve a spelling checker.
It came with my PC.
It plainly marks four my revue
Mistakes I cannot sea.
I’ve run this poem threw it.
I’m sure your pleased two no,
Its letter perfect in it’s weigh
My checker tolled me sew.
Technical Writing
24
Group Exercise
• Fix the poem to be grammatically correct.
• Further exercise: Make the above sentence
concise
Technical Writing
25
What is a Paragraph?
• It is a sentence or group of sentences that
expresses a single idea
• It often contains a statement, support for that
statement, and a summary
Technical Writing
26
Document Organization
• Provide an introduction, a body, and a
conclusion
• Use a subject line and itemization of points
rather than transitional words
• Uses topic sentences only when needed
• For some documents, alphabetize certain
sections
Technical Writing
27
Document Organization
• Put the most useful, general information first
• Follow it with detail
Technical Writing
28
Style
• Use short, denotative words, short sentences,
and short paragraphs
• Use diagrams and graphics if necessary
Technical Writing
29
Document Design
• Use highlighting techniques, such as graphics,
headings, subheadings, various fonts (but not
too many), white space, bullets, etc.
• For sequential instructions, use numbered lists
• For longer documents, include a table of
contents and an index
• For online documents, use hyperlinks
Technical Writing
30
Document Design
• What is a font?
• How many are on this slide?
Technical Writing
31
Exercise
• Write a single paragraph about the shirt
(blouse, top, etc.) you’re wearing right now.
Be precise and descriptive. There is no length
limit.
Technical Writing
32
Five Traits of Technical Writing
•
•
•
•
•
Clarity
Conciseness
Accessible document design
Audience recognition
Accuracy
Technical Writing
33
Clarity
• Technical writing must be clear, easy to
understand
• Who has ever gotten unclear instructions?
• “Put that thing over there.”
• “The program didn’t work.”
• Or this homework assignment: “Write a
program that finds prime numbers.”
Technical Writing
34
Clarity – Reporter’s Questions
• Who? Who is your audience? Are they
beginners or experts?
• What? What do you want your audience to
know? What do you want them to do?
• When? In many kinds of technical writing,
things happen in a sequence.
• Where? Where will the work take place?
• How? How should the task be performed?
Technical Writing
35
Clarity
• Avoid imprecise words: many, few, short,
often, recently, thin, etc.
• Use precise words and terminology:
– Connect a 20K-ohm, ¼-watt resistor in series with
the light sensor
– Don’t block the user interface thread for more
than 2 seconds
– Use four inches of 26-gauge black wire
Technical Writing
36
Clarity
• Front-load your sentences with important
information:
• “Unfortunately, your program has timed out.”
• “Network connection unavailable. Call 5555
for technical support.”
Technical Writing
37
Clarity
• “I had eggs scrambled with cheddar cheese
and toast for breakfast this morning.”
• Were the eggs scrambled with cheese and
toast?
• Keep terms consistent. For example, I often
use method and function interchangeably, but
there really is a difference.
Technical Writing
38
Conciseness
• Concise means expressing much in few words
• Keep it short and to the point
• Its opposite is pleonasm, which is using many
words where few will do
• Documents must often fit in a specific physical
space
– Resume must be one page
– Car owner’s manual must fit in glovebox
Technical Writing
39
Conciseness Counterexample
“In order to facilitate an efficient meeting and fuel
thought processes prior to June 25, I want to
provide you with a brief overview of discussions
recently carried out at the director and manager
level within the process. These discussions involved
personnel from Accounts Payable, Information
Services, Procurement/Materials Management,
Financial Systems, and Property Accounting,
centering on a proposed framework for managing
process improvement moving forward.”
Technical Writing
40
Exercise
• Rewrite the previous slide to be concise and
clear.
Technical Writing
41
Conciseness
• Use short words instead of sesquipedalianisms
Use this
Rather than this
Use
Utilize
Try
Endeavor
End
Terminate
Do or perform
Accomplish
Work
Collaborate
Soon
Presently
Job
Employment
Technical Writing
42
Conciseness
• From the department of redundancy
department:
• We collaborated together on the project.
• The system will cost the sum of $30,000.
• The other alternative menu item is fish.
• We could not find the file you requested.
Technical Writing
43
Conciseness
• Avoid prepositional phrases: “Switches modes
quickly” not “Switches modes at a high rate of
speed.” (What else should you do with this?)
• Avoid passive voice: “The system processes
approximately 2000 records per minute” not
“Approximately 2000 records per minute are
processed by the system.”
Technical Writing
44
Exercise
• Spend a minute or so looking at your
computer. Then write instructions for
disassembling it.
Technical Writing
45
Accessible Document Design
• Document design refers to the physical layout
• Often, technical documents are used for
reference, not meant to be read in their
entirety
• Your reader may not even be interested in the
subject
Technical Writing
46
Document Design
• Long documents require a table of contents
and an index.
• For example, programming manuals, patents,
etc.
• Use hyperlinks in online documents
• Use bookmarks in PDFs
Technical Writing
47
Document Design
• Don’t use paragraphs that look like a “wall of
words.”
• Use tables to present information clearly:
Grading Criteria
Program works according to your specification and does not
crash under testing.
Program uses the two principles you outlined in your
description.
Clean object-oriented design
50 points
Program comments and naming conventions
10 points
Technical Writing
30 points
10 points
48
Know Your Audience
• There are three different kinds of audiences:
• High-tech peers – these are people in the same
profession at roughly the same level as the writer.
The PCBUS manual is written at this level.
• Low-tech peers – These are people who may not
have the same level of expertise as you but they
need to understand the subject. The summary of
a software design document written for a
manager is an example.
Technical Writing
49
Know Your Audience
• Everyone else – The person setting up a TV set
or video recorder, the person who just wants
to use her computer to send e-mail or play
games, and the person assembling a bicycle
are all in this category.
Technical Writing
50
Accuracy
• Technical writing must be accurate
• It must exactly represent the function of the
program, the steps to make bread, the
directions to your house
• Inaccuracies can cause the document to be
anything from annoying to dangerous
• Accuracy often involves counting and
measuring
Technical Writing
51
Accuracy
• Missing information can be as dangerous as
wrong information
• For example, in PCBUS the KEYIN verb does
not usually affect the flags. However, it can
under certain circumstances, and this must be
carefully documented. Otherwise the reader
will assume they are never affected.
Technical Writing
52
Accuracy
• Finish writing, wait a day or so, then re-read
and see what you might have left out or
gotten wrong
• Have someone else read it
• Read it aloud
• Read it backwards or upside-down
Technical Writing
53
Accuracy
• Difference between accuracy and
incompleteness or imprecision:
• “Use 4 feet of 3/8-inch rebar” when the real
requirement is for ½-inch rebar.
• “Use 4 feet of rebar.” Does not specify
diameter, so the builder isn’t sure.
Technical Writing
54
Exercise
• Describe, as accurately as possible, the same
pen or pencil you described previously. Do
not look at your previous work.
Technical Writing
55
Applications
•
•
•
•
Letters – Sales, inquiry, cover letter, etc.
Memos
E-mail
Reports – Proposals, trips, lab reports, etc.
Technical Writing
56
Conclusion
• Technical writing is an extremely important
skill
• There is a good market for technical writers
and technical editors, and it can be a
rewarding job
• With practice and attention, you can become
a much better writer
Technical Writing
57
References
• A Teacher’s Guide to Technical Writing by Dr.
Steven M. Gerson
• The Elements of Programming Style by
Kernighan and Plauger
• The Elements of Style by Strunk and White
Technical Writing
58