How to Compose Technical Documentation

1

Deliverable 1: How to compose the Technical Documentation©KarenThompson● DepartmentofEnglish● UniversityofIdaho

What is technical documentation?

• The phrase technical documentation is commonly used in one of two ways.

1. User-oriented technical documentation.2. Project-oriented technical documentation.

2

User-Oriented Technical Documentation

• Refers to instructions, manuals, specifications or other materials produced by a manufacturer or developer.

• The purpose is to help consumers use a product or application.

• It is external communication written for those outside of the business. It should be consistent in design and support the brand identity of a business.

3

Project-OrientatedTechnical Documentation

• Refers to reports and other forms of communication made by a project team to plan how 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, composed for those within the business. How it is designed will vary based on the culture of that specific business and is often discipline specific.

4

Examples of differences in discipline-specific 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.

5

• Computer Science

• Documentation is embedded in the source code throughout the development process of software to identify the qualities or attributes of a system.

Deliverable 1: Project-Oriented Technical Documentation

• The type of documentation you will write for this project will be project-oriented.

• The aim is to provide you with applied practice, on a small scale, in composing project-oriented technical documentation.

6

• As you go through this slidedoc lecture, you may be unsure of just how to plan deliverables 2 and 3 in order to write the technical documentation.

• That is similar to what happens when a project team is planning a project they have never done before, so be patient with yourself and the course materials.

• BUT always email me with questions whenever you feel confused to the point of getting frustrated.

7

Timetosendthatemail.

Yeah,doitnowbeforeyouneedadentist.

Audience for the Technical Documentation

• Write the technical documentation to me, in the form of a memo report.

• In it, you will explain specific planning decisions for deliverables 2 and 3 of this project.

• In this lecture, I will explain the planning decisions you will need to make, but first, I want to clarify the difference between a technical definition and a technical description.

8

9

Technical Definitions:• Answer the question: what is X?

The answer to this question may range from a short phrase in parentheses to several pages.

Technical Descriptions:

• Answer the question: how does X work? or how is x doing? (the state or condition of x).The answer to this question may range from a short paragraph to several pages.

A technical definition will often need to describe, briefly and in general, how something works in order to define what it is and a technical description will almost always begin with a sentence-level definition before describing how something works.

It is the different questions each answers that make them different from one another.

Planning Deliverable 2:

Extended SlidecastTechnical Definition

10

• Deliverable 2 is an extended technical definition in slidecast form. A slidecast is a slideshow with voice-over narration.

• Your slidecast will be about 3 minutes and consist of at least six slides. Five of these you will narrate and the sixth is a bibliography that cites any images you use from sources.

• Complete the following steps to make decisions necessary to plan this deliverable and compose the section in your technical documentation that provides me with these decisions.

11

A brief overview of deliverable 2 to help in planning.

Step 1: Choose a Term

• It may be a word or phrase and can be an • object; • process; • mechanism; • product; • phenomena; • animal or plant; • a problem that has a name; • a theory; • or a concept.

• The term you choose should be in your field of study if possible or, if not, it should be a term you are knowledgeable about. It should be a term that would lead to a substantive technical definition.

12

• Deliverable 3 of this project requires you to describe how a process or mechanism works, so it is a technical description not a technical definition.

• If for deliverable 2 you choose to define a process or mechanism, your definition should not be extended by focusing on how it works (remember that definitions answer a different question from descriptions). Instead, choose one or more rhetorical moves covered in this slidedoc lecture.

• Or choose a different term for the extended technical definition if that seems easier, and/or ask me for help.

13

Step 2: Identify the audience.• After you have chosen a term, identify a specific non-specialized

audience who would need more than just a sentence-level definition of this term and why.

• The goal is to help someone who is not in your field of study to understand the term you are planning to define and the process or mechanism you are planning to describe. This means they would be lay persons without the specialized knowledge you possess.

• WARNING: do not choose students as your audience because the goal is not to be in the position of a teacher. Your goal is to help a non-specialized audience understand the term for a specific purpose.

14

Step 2: Identify the audience continued• To help you choose a non-specialized audience and determine

why they would need your definition, think it through by posing questions.

• Who would be better able to make a decision about something, understand how something affects them, or interpret something after watching your slidecast extended technical definition?

• What level of education would your audience have?

15

Examples:• How would an extended definition of a non-governmental

organization (NGO) help a non-specialized audience decide if they should contribute money to support the funding of an NGO?

• How would an extended definition of a relay system help an audience of city council members decide if purchasing this type of system would be appropriate for their city?

16

Examples continued.

• How would an extended definition of wildfire levels help a non-specialized audience interpret a map showing the extent and severity of wildfires and hazardous air alerts in their area?

• How would an extended definition of trophic cascade help a non-specialized audience understand how this theory applies to wildlife management decisions that affect them as stakeholders?

17

• Choose one or more of the following to extend your definition based on what your audience would need: • Classify x with more detail.• Contrast x with something different.• Compare x to something similar.• Explain the causes and effects of x.• Provide an example of x.• Describe some of the history behind x.• Describe physical characteristics or qualities of x.

• And you are required to use ONE of these moves:• Use a metaphor to explain what x is like.• Use analogy to compare x to something familiar.

18

Step 3: Plan how you will extend (develop) the definition of your term beyond a sentence-level.

Planning Deliverable 3:

Technical Description

19

A brief overview of deliverable 2 to help in planning.

• For this part of the project, you will be describing a process or mechanism for print delivery.

• This means you will create a document file and use one or more images to work cohesively with the description you write.

• Complete the following steps to make decisions necessary to plan this deliverable and compose the section in your technical documentation that provides me with these decisions.

20

Step 1: Choose a Process or Mechanism

• It should be in your field of study if possible or a process or mechanism you are knowledgeable about.

• Avoid choosing a trivial process or a process that is so basic it cannot lead to a substantive technical description.

• If you are unsure if your process is trivial or too basic, just ask me to give you feedback on your idea.

21

• Be careful when planning decisions for project 2 that you are not planning to write a set of instructions.

• Technical descriptions are different from technical instructions:• technical descriptions answer the question: how does x work?• technical instructions answer the question: how do I do x?

22

Step 2: Identify the audience.• After you have chosen a term, identify a specific non-

specialized audience who would need your technical description and why.

• This means your audience would not have the professional or specialized knowledge that you possess (i.e. laypersons) nor would they be interested in joining your field of study (i.e. novices).

The same warning about novice audiences given for the extended slidecast technical definition applies to choosing the audience for your technical description.

• To help you choose an audience and determine why they would need the description, think it through by posing questions.

23

Examples:• How would a technical description about how solar panels

work help homeowners decide if they should purchase this type of alternative power system for their home?

• How would a technical description of how Alzheimer’s disease progresses through 7 stages help caregivers make decisions about their loved ones?

• How would a technical description of modern nuclear power plants help restore public confidence in this type of power?

24

Examples continued.

• How would a technical description of a how a recumbent bike functions, including its features, help consumers decide if the bike is right for them?

• How would a technical description of how wind turbine power is generated help a landowner decide to lease land to an energy company for a wind farm?

• How would a technical description of how gerrymandering works help voters decide if they should support legislation aimed at ending this process?

25

Step 3: Choose or Create the Visual(s)

• I strongly encourage you to create the visual(s) yourself because the most common weakness I see in student work is choosing a source visual that is far too complicated for the audience.

• Or a source image may be labeled in such a way that prevents the writer from composing a description that works cohesively with the visual.

• If you decide to use one or more visuals from sources, be certain to adapt the visual(s) to work for the description you will write. For more information see the lecture on how to compose the technical description.

26

Step 4: Decide the organizing pattern.

• Most technical descriptions use versions of a division pattern.

• This means that some things can best be understood as a series of smaller parts, phases, or steps.

• There are three variations to a division pattern. You will need to decide which one would be best for your technical description and know its name.

27

Sequential Pattern

This pattern organizes the descriptive detail according to a sequence that emphasizes phases or steps.

28

Chronological Pattern

This pattern organizes the descriptive detail through a sequence that emphasizes time.

29

Parts to Whole Pattern

This pattern organizes the descriptive detail based on components or parts of something and how each part or component works or functions.

30

How to Format and Write the

Technical Documentation

31

Use memo format and one of the rhetorical moves you learned in project 1 to compose the introduction to your technical documentation.

32

For the Extended Technical Definition explain the following:

• Audience and Need: who is the non-specialized audience for your extended technical definition? And what need does your definition meet?

• Extending the Definition: explain the rhetorical moves, including the required metaphor or analogy, you will use to extend (i.e. develop) the definition.

If you need help with how to decide the metaphor or analogy, use the optional lecture on this subject in bblearn.

33

For the Technical Description explain the following:• Audience and Need: who is the non-specialized audience

for your technical description? And what need does your description meet for this audience?

• Visual Choice: explain if you will create the visual(s) and how you plan to do this or if you will be using one or more source visuals.

• Organizing Pattern: what is the name of the organizing pattern you will use for the technical description?

34

Use document design • headings, • white space, • visual hierarchy,• left justification,• single-spaced text with line

of white space between paragraphs.

35

Some final tips:• TIP 1: some students can easily make the planning

decisions and write the technical documentation after they finish this lecture.

• TIP 2: other students find it easier to write the technical documentation after looking at the lectures for deliverables 2 and 3.

Do what works best for you.

36