Technical Writing

Computer Science and Engineering ■ College of Engineering ■ The Ohio State University

Lecture 24
What Is “Technical Writing”?
Computer Science and Engineering ■ The Ohio State University

□ Writing we do as part of our jobs

□ Possible purposes:
■ Inform
■ Instruct
■ Persuade
■ Call to action
□ Missing from this list:
■ Entertain
Effective Technical Writing
Computer Science and Engineering ■ The Ohio State University

1. Engages a specific audience

2. Uses plain and objective language
3. Stresses presentation (obvious
structure, understandable at a glance)
4. Employs visual aids
Why Bother?
Computer Science and Engineering ■ The Ohio State University

□ Communication is fundamental in
society
■ Politics, law, science, personal lives, health,
…
□ Fundamental in personal success:
■ Good idea
■ Ability to communicate that idea
□ Highly valued by employers
Writing in Computer Science
Computer Science and Engineering ■ The Ohio State University

□ Taking exams
□ Documentation (for users and
developers)
□ Reports and memos
□ Papers (journals, conferences,
magazines…)
□ Proposals
□ Reviews of others’ work
□ Books
Good and Bad News
Computer Science and Engineering ■ The Ohio State University

□ The bad news

■ Most of us are not very good at it
■ We enjoy “technical” challenges much more
□ The good news
■ Writing is actually not too different from
computer science!
Writing Code vs Writing Prose
Computer Science and Engineering ■ The Ohio State University

Programming Technical Writing

Need to identify: Need to identify:

□User □Audience
□Problem/Need □Purpose
□Features □Cognitive depth
□User interface □Style and tone

"preprogramming" "prewriting"
Software/Document Engineering
Computer Science and Engineering ■ The Ohio State University

Soft Development Doc Development

□ Requirements and □ Prewriting

design
□ Implementation □ Composition
□ Testing □ Reviewing
□ Debugging □ Revising
Analyzing the Audience
Computer Science and Engineering ■ The Ohio State University

□ Few people read this stuff for fun

□ Must correctly identify a “customer” and
what that customer’s needs are
□ Consider writing an audience profile
■ Novice, technician, expert, manager, VC, …
■ Reading level
■ Motivations, biases, expectations, …
□ Explicitly state assumptions made on
background, motivation, needs, etc.
■ “The reader is expected to be familiar with the
predicate calculus.”
■ “This manual is designed for application
programmers who write S47G applications for
the insurance industry.”
Technical Audience
Computer Science and Engineering ■ The Ohio State University

□ Function-oriented organization
■ E.g., alphabetical listing of all functions
□ Want a complete (exhaustive) resource
■ All information they might want is there
somewhere
□ Willing to spend a great deal of time
■ Will read the document carefully
Customer Audience
Computer Science and Engineering ■ The Ohio State University

□ Prefer task-oriented organization

■ E.g., enumerated steps for each possible
task
□ Want just the necessary information
■ Only the information critical to their jobs is
there
□ Will spend as little time as possible
■ Must be concise and easy to read
Identify the Purpose
Computer Science and Engineering ■ The Ohio State University

□ Golden rule of business communication

■ Begin with clear statement of what you
want!
■ "Start with the ask"
□ Larger documents are no different
■ What information are you trying to impart?
■ What are you trying to teach?
■ What view do you want the reader to
adopt?
■ What action do you want done?
The Depth of Writing
Computer Science and Engineering ■ The Ohio State University

□ Bloom’s taxonomy □ Revised by

of cognition Anderson &
(1957): Krathwohl (2001):
1. Knowledge 1. Remember
2. Comprehension 2. Understand
3. Application 3. Apply
4. Analysis 4. Analyze
5. Synthesis 5. Evaluate
6. Evaluation 6. Create
Verbs in Statement of Purpose
Computer Science and Engineering ■ The Ohio State University

□ Knowledge (Remember)
count, define, draw, identify, indicate, list,
name, quote, recall, recite, recognize, record,
state, tabulate, trace, write
□ Comprehension (Understand)
compare, compute, contrast, describe,
differentiate, discuss, distinguish, estimate,
extrapolate, interpolate, predict, translate
□ Application (Apply)
apply, calculate, classify, complete, construct,
demonstrate, employ, examine, illustrate,
practice, relate, solve, use
Verbs in Statement of Purpose II
Computer Science and Engineering ■ The Ohio State University

□ Analysis (Analyze)
■ analyze, detect, explain, group, infer, order,
relate, separate, summarize, transform
□ Application (Apply)
■ apply, calculate, classify, complete, construct,
demonstrate, employ, examine, illustrate,
practice, relate, solve, use
□ Synthesis (Create)
■ arrange, combine, construct, create, design,
develop, formulate, generalize, integrate,
organize, plan, prepare, produce, specify
□ Evaluation (Evaluate)
■ appraise, assess, critique, determine, evaluate,
grade, judge, measure, rank, select, test
Prewriting: Getting Started
Computer Science and Engineering ■ The Ohio State University

□ Read the question / problem statement

carefully
□ Make a list of the required cognitive
tasks
□ Assess what you know
□ Compare this knowledge with the level
of the required cognitive task
Example
Computer Science and Engineering ■ The Ohio State University

“Compare the performance of two cache

replacement algorithms”
□ Cognitive tasks
■ Compare
■ Contrast
■ Maybe analyze and recommend?
□ Recall various issues in cache
algorithms
Prewriting Tasks
Computer Science and Engineering ■ The Ohio State University

□ Quick list
■ Specific points for each cognitive task
□ Brainstorm
■ List everything you know about the topic
■ Do not judge or weed anything out
■ Objective: quantity
□ Review list
■ Assess where research is needed
Prewriting Tasks II
Computer Science and Engineering ■ The Ohio State University

□ Choose a single point that will be in the

final product and outline a section to
develop that point.
□ Involve others as appropriate.
□ Do the research.
□ Plan the format.
This is not a linear process!
Prewriting Tasks III
Computer Science and Engineering ■ The Ohio State University

□ Outlining
■ Get the planned structure down
■ Avoid forgetting a key point
■ Check for the logical flow of arguments and
information
This is an easy step to skip, but good work
here will pay dividends in the future!
Writing the Document
Computer Science and Engineering ■ The Ohio State University

□ The better the preparation in the

prewriting phase, the smoother this
goes.
□ Regardless, it’s still work!
□ Requires tools, skills, practice,
experience, and motivation.
Technical Writing: “Document Component
Engineering”
Computer Science and Engineering ■ The Ohio State University

□ Component = section of the document.

□ Often has its own heading.
□ Large components consist of smaller
ones.
□ Each (large enough) element from the
outline becomes a component
Advantages of Components
Computer Science and Engineering ■ The Ohio State University

□ The whole document is too intimidating

□ Obvious milestones
■ Reduces panic (you know where you stand)
■ Permits time budgeting
□ Reduces writing to a step-by-step
process
□ Instant gratification
□ Easy cure for writer’s block: work on a
different section
Writing a Component
Computer Science and Engineering ■ The Ohio State University

□ Know the purpose

□ Have all the information
□ Different strategies:
■ Write a draft using sentences
■ Jot down points in any form, then flesh out
into sentences
■ Combination (sentences, phrases, points)
Overcoming Writer’s Block
Computer Science and Engineering ■ The Ohio State University

□ Start anywhere
□ If the problem is lack of information, go
back and do more research
□ Explain it to someone else (verbally)
□ Work on a different section
□ Take a walk
□ Imagine life when you are done
Overcoming Writer’s Block II
Computer Science and Engineering ■ The Ohio State University

□ Force yourself to sit at your desk until

done
□ Revise your outline or organization
□ Revise some section you’ve already written
□ Change your environment
□ Diagram the structure of the component
□ Set an impossible schedule… and then
panic!
□ Take a break
Rhetorical Patterns
Computer Science and Engineering ■ The Ohio State University

□ Every culture has well-established

patterns of exposition
■ Ready-made structures into which specific
information may be dropped
□ The reader is already familiar with these
patterns
□ The technical writer does not have the
time (or skill) to invent new ones
General-to-specific Pattern
Computer Science and Engineering ■ The Ohio State University

□ Often used for introductory section

□ Start with the most general statement
“More computing resources are devoted to
the management of data than to any other
task”
□ Gradually get more specific
“This program simplifies the manipulation of
numeric data on a personal computer”
□ Finally specific statements
Classification Pattern
Computer Science and Engineering ■ The Ohio State University

□ Organize information by dividing it into

categories
■ E.g., a section on each of initialization, data
entry, selection, access control, etc…
□ Within each category, present parallel
information
■ E.g., purpose, prerequisites, results, error
messages, alternatives, references, etc…
Comparison-contrast Pattern

(Point-by-point)
Computer Science and Engineering ■ The Ohio State University

□ Consider one aspect at a time

■ In football, the ball may be thrown forward
from behind the line of scrimmage
■ In rugby, only lateral passes are allowed
■ In football, play ends when the ball-carrier
is tackled
■ In rugby, play continues after a tackle, but
the tackled player must release the ball
Comparison-contrast Pattern

(Whole-to-whole)
Computer Science and Engineering ■ The Ohio State University

□ Two ways to create a new object

(zack)
1. From the command line
– On the command line, type “edit zack”
– Fill in attributes of the presented template
– Select Save from the File menu
2. From within the application
– Select New from the File menu
– Fill in attributes of the presented template
– Select Save As from File menu, and type
“zack”
Definition Pattern
Computer Science and Engineering ■ The Ohio State University

□ Typically short and simple

□ Example
■ “Undo is a function that restores an object
to its state immediately prior to that last
operation”
■ Places “Undo” in the class of functions, then
distinguishes it from other functions
Chronological Pattern
Computer Science and Engineering ■ The Ohio State University

□ Typical for task-oriented instructions

□ Given in the order in which they must
be performed
Cause-and-effect Pattern
Computer Science and Engineering ■ The Ohio State University

□ Often used for error messages

□ Give a list of error messages
■ ordered alphabetically, by error number, …
□ For each message, list the possible
causes
■ ordered most to least likely
□ After each cause, give the action(s) the
user should take to recover
Putting Components Together
Computer Science and Engineering ■ The Ohio State University

□ Add headings (part, chapter, section, …)

□ Add transitions where needed
■ Important to prompt reader for what to
expect, or to reinforce that some change is
coming
Possible Transitions
Computer Science and Engineering ■ The Ohio State University

□ Moving to the next point in a sequence

■ “Firstly, secondly, …”
□ Contrasting item or viewpoint
■ “However, on the other hand, otherwise,…”
□ A result or conclusion
■ “Therefore, in consequence, …”
□ Relating things in time
■ “Now, then, soon, immediately,…”
Possible Transitions
Computer Science and Engineering ■ The Ohio State University

□ Introducing an example
■ “For example, that is, …”
□ Further strengthening a point
■ “Moreover, similarly, further, …”
□ Concluding
■ “In conclusion, in summary, finally,…”
Preliminary Draft
Computer Science and Engineering ■ The Ohio State University

□ Starting is always difficult

■ Helps to remember it’s just a draft!
□ Don’t worry about spelling, grammar,
form
□ Spend effort on sound communication
of major points
□ Fill in your outline
Middle Draft
Computer Science and Engineering ■ The Ohio State University

□ Build on the base of the preliminary

draft
□ Refine the organization and fill in points
□ Ensure each point belongs in that
paragraph
□ Cut and paste
□ Play with the text
■ Font, layout, spacing, page count
Final Draft
Computer Science and Engineering ■ The Ohio State University

□ Spelling and grammar

■ Run the spell checker, but that’s not
enough!
□ A “which” hunt
□ Word choice
□ Transitions
□ Typos
□ Pagination
Revising
Computer Science and Engineering ■ The Ohio State University

□ Where bad writing becomes good

writing
□ First draft is always bad
■ Tempting to become attached to text we’ve
written
■ Write the first draft anticipating that it will
change in the future
Revising Tasks
Computer Science and Engineering ■ The Ohio State University

□ Add flow and smooth transitions

□ Careful, accurate movement from one
point to the next, one section to the
next
□ Make decisions that have been put off
□ Reduce wordiness
□ Clarify subordination relationships
between points
Red Flag – Inconsistent View
Computer Science and Engineering ■ The Ohio State University

□ Changing from 2nd to 3rd person

■ “Limit your disk storage to 100 Mb. The
user can submit a request for more storage
space to the system administrator.”
■ “Limit your disk storage to 100 Mb. For
more storage space, you can submit a
request to the system administrator.”
Red Flag – Passive Voice
Computer Science and Engineering ■ The Ohio State University

□ The verb expresses what is done to the

subject (by someone or something)
□ Occasional use is OK (and even
unavoidable in many technical
documents)
□ But excessive use weakens your writing
■ “This error is used by the parser to
indicate…”
■ “The parser issues this error to indicate…”
Red Flag - Wordiness
Computer Science and Engineering ■ The Ohio State University

□ In the final analysis, the end result of a

wordy document is increased cost in
terms of pages of paper, bytes on a
disk, and inefficient use of the reader’s
time and the writer’s effort
□ Words cost money. It is cheaper to
print a short book than a long one.
Red Flag – Faulty Parallelism
Computer Science and Engineering ■ The Ohio State University

□ The use of different grammatical

constructs in a parallel structure
□ Consider the list:
■ Preparing for installation
■ How to configure
■ Do you want the advanced options?
Red Flag – Dangling Modifier
Computer Science and Engineering ■ The Ohio State University

□ The use of a verbal phrase that does not

connect (or modify) anything else in the
sentence
■ “After typing enter, the system will continue
with the second pass over the program”
■ “After you type enter, the system will
continue with the second pass over the
program”
Red Flag – Ending a Sentence With a Preposition
Computer Science and Engineering ■ The Ohio State University

□ Example:
■ “Before using the software, you must set it
up”
■ “Before you can use it, you must set up the
software”
■ “You must set up the software before using
it.”
□ Winston Churchill:
■ “That is criticism up with which I will not
put.”
Red Flag – Splitting a Verb
Computer Science and Engineering ■ The Ohio State University

□ Dogma: Avoid splitting an infinitive

■ Infinitive is “to” + verb, or “will” + verb
□ eg “to think”, “to breathe”, “will dance”
□ Avoid putting an adverb inside
■ Patients should try to if possible avoid going
up and down the stairs
■ If possible, patients should try to avoid…
□ Famous violation of dogma: Captain Kirk
■ “Its five-year mission, to boldly go…”
□ Famous over-use of dogma: Chief Justice
Roberts
■ “…will execute the office of the president of
the United States faithfully…”
Red Flag – Provincial and Sexist Language
Computer Science and Engineering ■ The Ohio State University

□ Unless you are sure your readership is

homogeneous, be sensitive to and
inclusive of many cultures and both
genders
□ Example a list of names:
■ “Bill White, Ken Williams, and Bob Smith”
■ “Chris Amini, Lea Sanchez, and Rei Chi Lee”
Red Flag – “Which” vs. “That”
Computer Science and Engineering ■ The Ohio State University

□ Simple rule: if “that” sounds OK, use it!

□ Use “which” with nonrestrictive clauses
□ Use “that” with restrictive clauses
□ Example:
■ “Ed’s country house, which is located on
five acres, had bats in the attic.”
■ “The house that sat on the top of the hill
had bats in the attic.”
Red Flag - Utilize
Computer Science and Engineering ■ The Ohio State University

□ Why would anyone utilize the word

“utilize” when the word “use” works just
as well?
Things to Check – Appropriate Style
Computer Science and Engineering ■ The Ohio State University

□ Amount of detail
■ Verbose vs. terse
□ Formality
■ Formal vs. informal
■ Use of contractions, informal language, slang
□ Tone
■ Distant, warm, familiar, intrusive
□ For whatever style is chosen, consistency
is very important
Examples
Computer Science and Engineering ■ The Ohio State University

The component type which contains the

math definition of the component is
stored in the file called Type.h which
provides the client with the general
component description.

The component type, which contains the

math definition of the component, is
stored in a file called Type.h. This file
also provides the client with a general
description of the component.
 Computer Science and Engineering ■ The Ohio State University

If users input a file has invalid header

record which contains more than 13
characters, the program will pop up an
error message: “Parse Error: Invalid
header record”, then it terminates.

If the input file given by the user does not

begin with a valid header record, the
following error message is displayed:
“Parse Error: Invalid header record”.
 Computer Science and Engineering ■ The Ohio State University

The overall is contained in

Machine_Program.cpp

The main program is contained in the file

Machine_Program.cpp.
 Computer Science and Engineering ■ The Ohio State University

If the user wishes to quit, then a “q” will

be entered.

To quit, the user must enter “q”.

 Computer Science and Engineering ■ The Ohio State University

The function will return 0 if successful,

and an integer value if an error of any
type is recorded.

The function returns an integer. A return

value of 0 indicates successful
completion, while a non-zero return
value indicates an error.
 Computer Science and Engineering ■ The Ohio State University

So now your wondering how these classes

will work together? Well it’s pretty
simple these classes will extend the
functionality of Score.java and
Error.java. So, what does that mean?
Well, it means that…

Please give me an E.
Summary
Computer Science and Engineering ■ The Ohio State University

□ Technical writing requires work,

practice, skill, technique, time; not
talent.
□ The first draft is always bad writing.
Allow time (and energy) for revisions.
□ There is no substitute for having
something to say. You can’t bluff it.
Time
Computer Science and Engineering ■ College of Engineering ■ The Ohio State University

Bonus material
Interval vs Point
Computer Science and Engineering ■ The Ohio State University

□ Different questions:
■ “How long did it take to run 5k?”
■ “When is our final exam?”
□ Answering “how long?” is easy
■ Count the number of elapsed seconds
■ Easy to code
□ Answering “when?” is tricky
■ 8 am (Dec 17, 2014) is not sufficient
■ Meaning depends on geolocation!
■ Even dates (Dec 17th) have this problem
Solving Time/Place Problem
Computer Science and Engineering ■ The Ohio State University

□ Fix one place on earth, and use that

location's time
■ We agreed (in 1884): Greenwich, England
■ Same location as used for longitude
■ "Prime Meridian" of longitude (ie 0°)
□ Aside: What are the co-ordinates of the oval?
■ Used to be called "Greenwich Mean Time"
□ Example
■ CSE 3901 final exam is at 1 pm on Dec 17,
2014
■ So why does it say 8 am on SIS?
Notation: Encoding Date/Time
Computer Science and Engineering ■ The Ohio State University

□ Computer scientists understand the

importance of representation/encoding
□ Big Endian
■ year-month-day hour:minute:second
2014-12-17 08:00:00
■ Benefit: lexicographic = chronological
□ Start at 0, not 1
■ Non-CS folks call this a "24-hour clock"!
■ CS folks call this… normal
■ 00:00 is midnight, 12:00 is noon
■ Benefit: Avoids am/pm ambiguities
Time Zones
Computer Science and Engineering ■ The Ohio State University

□ Unfortunately, people want their clocks to

show 12:00 when the sun is "highest"
□ Solution: time zones
■ Politically defined region that uses the same
offset from Greenwich
□ Abbreviations
■ EST = UTC-5:00 ("Standard", ie winter)
■ EDT = UTC-4:00 ("Daylight savings" summer)
□ To report a time, append time zone
■ 2014-12-17 08:00:00 EST
■ 2014-12-17 08:00:00 UTC-5:00
■ 2014-12-17 13:00:00 UTC
Mixing Intervals and Points
Computer Science and Engineering ■ The Ohio State University

□ Mapping between these is difficult

□ Eg: Run a task every day at 9 am
■ Naïve solution: java.util.Timer’s schedule
schedule (TimerTask t, Date first,
long period)
■ Period is an interval (number of milliseconds)
schedule(job, today, 86400000);
□ Problem?
■ Not every day has 24 hrs!
■ Daylight savings ==> a day can be 24, 23, or
25 hours long
End of the World
Computer Science and Engineering ■ The Ohio State University
From Intervals to Points
Computer Science and Engineering ■ The Ohio State University

□ Measure interval from a fixed point

■ Called “epoch”
■ Needed for both date (BC/AD) and time
□ Unix: chose Jan 1, 1970
■ long time_t, count of elapsed seconds
■ What time is it? Approx. 1,416,580,000
□ http://www.unixtimestamp.com/index.php
■ Stored as a (signed!) 32-bit integer
□ “max time” = 232-1 = 2.1 billion = 68 years!
□ Will overflow on Jan 19, 2038
□ Solution: use 64 bit!
■ Postpones the problem for 290 billion years…
This hour has ?? minutes…
Computer Science and Engineering ■ The Ohio State University

69
Seconds, Minutes, Hours, Days
Computer Science and Engineering ■ The Ohio State University

□ Days do not divide years evenly

■ About 365.242199 days/year
□ But seconds do divide days evenly!
■ Exactly 24 * 60 * 60 = 86,400 s/day
□ Why?
■ Days & years are set independently by nature
■ Seconds are our invention
□ How long is a second?
■ Defined to be 1/86,400th of a day
■ SI second = 9,192,631,770 oscillations of a
caesium-133 atom (at rest, sea level, 0
Kelvin)
■ Just one problem… how long is a day?
1st Problem: Apparent Solar Day
Computer Science and Engineering ■ The Ohio State University
2nd Problem: Elliptical Orbit
Computer Science and Engineering ■ The Ohio State University

□
Equation of Time
Computer Science and Engineering ■ The Ohio State University
Do We Care?
Computer Science and Engineering ■ The Ohio State University

□ The equation of time lets you correctly

convert time to/from position of sun
■ At what time will be “local noon” today?
■ See: www.timeanddate.com/sun
□ This only matters if you care about the
exact position of the sun any given day!
■ So mostly no one cares
□ All we need is average length of full day
■ A “mean solar day”
■ Horizontal axis in graph of equation of time
■ Measure it, super accurately, then divide by
86,400
Now For the Really Bad News
Computer Science and Engineering ■ The Ohio State University
The Earth is Slowing Down
Computer Science and Engineering ■ The Ohio State University

□ Planet has been slowing down (and will

continue to slow down)
□ Today's "mean solar day" is longer than
it was 200 years ago!
■ We use the mean solar day of 1750-1892
(averaged)
□ Bad news: There are a bit more than
86,400 SI seconds / mean solar day
□ Really bad news: We can't predict the
size of this effect very far into future
GMT vs UT1 vs UTC
Computer Science and Engineering ■ The Ohio State University

□ GMT: Greenwich mean time

■ Antiquated: Should not be used today
□ UT1: Universal time
■ Time at prime meridian
■ Determined by celestial movements
□ TAI:
■ Ticks in SI seconds
■ Was equal to UT1 in the early 70's
□ UTC: Universal Coordinated Time
■ Ticks in SI seconds, like TAI
■ Periodically modified to match UT1
Leap Seconds
Computer Science and Engineering ■ The Ohio State University

□ Mean solar day is longer than 86400 SI

seconds
■ Tidal forces have slowed the rotation of the
earth
■ Must correct clock time to stay synched with
solar days
□ Leap second: 1 second insertion/deletion
■ Irregular occurrence, UTC decides
■ Based on observation, impossible to predict
■ Since 1972, there have been 25 additions, no
deletions
■ Most recent: June 30, 2012 (an addition)
Leap Second Episodes
Computer Science and Engineering ■ The Ohio State University
1 minute ≠ 60 seconds
Computer Science and Engineering ■ The Ohio State University

□ Addition/removal occurs during the last

minute of Dec 31 or Jun 30
□ Those minutes have 61 or 59 seconds!
23:59:58, 23:59:59, 23:59:60, 00:00:00…
□ Screen capture of the clock at time.gov
during a leap second:
More Complications
Computer Science and Engineering ■ The Ohio State University

□ GPS satellites don’t reset their clocks

■ GPS time was equal to UTC time in 1980
■ Since then, has missed 16 leap seconds
■ http://leapsecond.com/java/gpsclock.htm
□ Unix time decrements during leap second
■ Monotonic timer provided by NTP protocol
□ Not all countries have adopted UTC
□ Leap seconds will become more frequent
■ Proposals to abolish, replace with leap hours
And we care because…
Computer Science and Engineering ■ The Ohio State University
Summary
Computer Science and Engineering ■ The Ohio State University

□ Intervals vs points
■ Intervals are easy, points are tricky
■ Unix time: Seconds from 01/01/1970
■ Date/time is coupled to geolocation
□ Interval between 2 points is hard
■ # days / year can vary
■ # hours / day can vary
■ # seconds / minute can vary
□ Standardization
■ Mean solar day, SI seconds
■ They don't match: need leap seconds
□ UT1, UTC, TAI