Project 2: Slideshare 2 - How to Write the Technical Documentation

Transcript

1. 1 Deliverable 1: How to write the Technical Documentation
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.
20. Common Organizing Patterns 20
21. Sequential This pattern organizes information according to a sequence that emphasizes phases or steps. 21
22. Chronological This pattern organizes information according to a sequence that emphasizes time. 22
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
24. Comparison/Contrast This pattern organizes information based on differences (contrast) and similarities (comparison). 24
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