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
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
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
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.
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
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
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
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
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
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
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)
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
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
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
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.
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