2. 2
Table of Contents
Introduction...........................................................................................................3-6
About Deliverable 1: Technical Documentation ..............................................7
Audience For Your Technical Documentation..................................................8
Overview of Planning Steps.................................................................................9
Step 1: Identify the Context..........................................................................10-16
Step 3: for option 1: Plan How You Will Extend the Definition ...................17
Step 3: for option 2: Plan How You Will Develop the Description .............18
Step 4: Plan Number of Slides and Plan the Order.....................................19
Common Organizing Patterns.............................................................................20-28
How to Format and Write the Technical Documentation................................29-32
3. There are two types of technical documentation:
1. User-oriented technical documentation.
2. Project-oriented technical documentation.
3
INTRODUCTION
4. User-Oriented
Technical
Documentation
Refers to instructions, manuals or other
materials created to help consumers use
a product or application.
It is external communication, written for
those outside of a business, and what
medium it is produced in (print/electronic
or both) how it is formatted is based on
the style guide of that business.
4
5. Project-Oriented
Technical
Documentation
Refers to reports and other forms of
communication made by a project team
to plan how a project will be done.
The process of writing this type of
documentation is recursive. This means it
will likely change as a project progresses
from beginning to end.
It is a form of internal communication,
written to those inside the business. How it
is formatted will vary based on the culture
of a business or organization and is often
discipline specific.
5
6. Examples of differences in discipline-specific
project-oriented technical documentation:
Engineering • Documentation for a product will
be in the form of reports that
describe how work will be done to
design, build, test, and market it.
6
Computer
Science
• Documentation is embedded in
the source code throughout the
development process of software
to identify the qualities or attributes
of a system.
7. Deliverable 1:
Technical Documentation
The type of documentation you
will write for this project is
project-oriented.
The purpose is to give students
applied practice in writing
technical documentation, even
if it is only on the small scale of
this project.
7
8. Audience for the
Technical
Documentation
Write the technical documentation
to me (if you are in my section) or
your instructor if you are in another.
Your purpose will be to convey your
planning decisions in a memo
report.
This slidedoc will give you guidelines
about how to write the report, but
first you need to make some
decisions by going through a three
planning steps.
8
9. 1. Identify a context (audience and need) and decide if an
extended technical definition of a term and what it means OR a
technical description of a mechanism; process; animal, plant,
insect; geographical feature/place; or phenomenon will best be
able to meet that need.
2. Plan how you will extend the definition or how you will develop
the specifics and details needed for a technical description.
3. Plan how many slides you will likely need and choose an
organizing pattern for how you will arrange their order.
9
OVERVIEW of
PLANNING STEPS
10. Identify a
Context
The context is the audience and need.
You need to choose a specific non-
specialized (i.e. lay audience) and the
need will be to help the audience
make a decision or gain a better
understanding of something that
affects (or may affect) them.
The audience you choose may be a
single person or a group of people who
need to make a decision about
something and your slidecast will help
them do this.
10
Step 1
11. WARNING
Do not choose students as your
audience because the goal is not to
teach but to translate technical
information to a lay audience in order
to meet a need this audience has.
11
12. To help you choose a lay audience and determine why they
would need your slidecast, consider these questions:
• What audience need can be met by providing a wider focus (i.e.
more information beyond a sentence-level definition) to help the
audience gain a better understanding of something and/or make a
decision? If this is the need, choose option 1: technical definition.
• What audience need can be met by narrowing the focus to describe
with specifics and details what something is like and/or how it works to
help an audience better understand something and/or make a
decision? If this is the need, choose option 2: technical description.
The next slides show examples of audience/need statements.
12
13. Examples of context for option 1:
Extended Technical Definition
Trophic Cascade. My audience will be people in southern Idaho who
are concerned about wolf-reintroduction. My slidecast will be a
technical definition of trophic cascade that explains the role of
predators in a food web to help my audience gain a better
understanding of the pro wolf-reintroduction side of this debate.
Non-Governmental Organization (NGO). My slidecast will be a
technical definition of an NGO that explains the different types as
well as the services and humanitarian aide they provide to help a
legislator decide if he or she should continue to support the tax
exempt status of these organizations.
Protective Relay System. The context for my technical definition will
be an audience of city council members who need to decide if
purchasing this type of system would be appropriate for the backup
generators in their city. My slidecast will go over different types of
systems and the advantages and disadvantages of each.
13
14. Examples for Option 2:
Technical Description
Solar Panels. My slidecast will be a technical description of 1st, 2nd,
and 3rd generation solar panels to help homeowners decide which
generation of panels they should should purchase for their home.
Alzheimer's Disease. I will create a slidecast technical description
that describes what happens as a person progresses through the
seven stages of this disease to help loved ones prepare for what to
expect if a family member has been diagnosed with early onset of
Alzheimer's.
Rainbow Trout. My audience will be anglers who need a technical
description of different types of trout, so they will know which fish they
can keep and which ones need to be released.
14
15. When making planning choices about audience and need, avoid a
scientific "us" vs. an ignorant public "them" approach because it
frequently leads to logical fallacies like this:
Most people don't understand that dairy farmers who use rBST
have to care about their animals and the milk they produce or
they would quickly be out of business! A dairy farmer would
never inject cows with something that would make the milk
unsafe. My purpose will be to help the public realize that rBST is
safe by defining what it is, and that they should stop listening to
anti-science activists who claim it isn't safe.
15
Avoid Logical Fallacies
• Logical fallacy 1: overgeneralization (most people,),
• Logical fallacy 2: false equivalency (caring deeply = food safety)
• Logical fallacy 3: begging the question, (the debate is not about
what rBST is but whether it's safe)
16. Example revised:
If writing a technical description:
My purpose will be to write a technical description of how
rbST works to help consumers make a more informed
choice about whether they want to drink milk that is rBST
free or not.
If writing a technical definition:
The debate about whether or not rbST is safe affects food
labeling laws. My purpose will be to write an extended
technical definition that explains the history behind this
debate.
16
17. Plan how you will extend (develop) the definition by choosing one or
more of the following rhetorical moves:
• Classify x with more detail,
• Contrast x with something different,
• Compare x to something similar,
• Explain the causes and effects of x,
• Provide some of the history behind x,
• Explain the extent and severity of x,
• Use a metaphor to explain what x is like.
• Use an analogy to compare x to something familiar.
• Use an example of x.
17
Step 3 for Option 1:
Extended Technical Definition
18. Plan to begin the technical description with a sentence-level
definition and, if needed, a brief overview, and then develop
the description by choosing one or more of the following
moves:
• Describe in detail the specific features of x,
• Describe in detail the specific characteristics of x,
• Describe in detail specific behaviors of x,
• Describe in detail the specifics of what x is made of,
• Describe in detail the specifics of what x does,
• Describe in detail the specifics of how x works,
The following moves may also be used, but be sure to keep them within
the narrow focus of describing specifics and detail.
• Use a metaphor to explain what x is like,
• Use an analogy to compare x to something familiar,
• Use an example of x.
18
Step 3 for Option 2:
Technical Description
19. 19
Step 4: Plan Number of Slides and
How You Will Arrange their Order
The slidecast will need to be about 3 minutes. You should plan to
keep each slide to one topic, so think about how many slides you
will need.
A good approach is to think no more than 30 seconds per slide (so
six slides), but you may need more slides than this and to spend
less time on each slide.
Choose one of the following common patterns for how to arrange
the order of your slides. Be careful when choosing a pattern that it
fits for the option you chose.
23. Parts-to-Whole This pattern organizes
information based on
the components or
parts of something and
how each part or
component works or
functions.
23
25. Cause/Effect This pattern organizes
information based on
tracing a cause to an
effect or tracing an
effect back to its cause.
25
26. Order of Importance This pattern organizes
information based by
either starting with more
important information
leading to less
important or the
reverse.
26
More Important
Less Important
Less Important
More Important
27. General to Specific This pattern organizes
information based on
either starting with more
general information
leading to specifics or
the reverse.
27
General
Specific
Specific
General
28. How to Format and Write the
Technical Documentation
28
29. Use memo format and one of the rhetorical moves you
learned in project 1 to compose the introduction to your
technical documentation.
29
30. Use document design • headings,
• white space,
• visual hierarchy,
• left justification,
• single-spaced text with line
of white space between
paragraphs.
30
31. In the body of your memo, explain the following:
Term/Name, Audience, and Need:
• what is the term or name (word or phrase) you chose?
• who is the lay audience you identified? (it cannot be students)
• what need does this audience have that your slidecast will meet?
For Option 1:Extended Technical Definition: state the rhetorical
move(s) you will use to extend (develop) the definition beyond a
sentence-level.
For Option 2: Technical Description: state the rhetorical move(s) you
will use to develop specifics and details beyond a sentence-level.
Organizing Pattern: state the name of the organizing pattern you will
use to arrange the order your slides.
31
32. Write a standard
conclusion
End the memo with a clear
conclusion.
A simple conclusion can be:
• Offering to answer any
questions the audience
may have.
32
