Instructions and ManualsWhite Papers

Formal and Informal ReportsSome info from Markel - Chapter

19, mostly from Talalay

First Things First

• What is the difference between an abstract and an executive summary?

Abstract v Executive Summary Definitions

Abstract Definition• Abbreviated summary of a research article, thesis, review, conference

proceeding or any in-depth analysis of a particular subject or discipline• Helps the reader quickly ascertain the paper's purpose. • An abstract always appears at the beginning of a manuscript, acting as

the point-of-entry for any given scientific paper or patent application.

Executive Summary • Far more than an abstract merely presenting the rest of the document,

it's your unique opportunity to convince the reader that your proposal provides the best value proposition: the best benefit at the lowest cost.

• The more technical your proposal, the more critical the executive summary is likely to be, because, unlike the abstract, the executive summary concentrates on substantiating the benefits for the customer.

What is a White Paper?

What is a White Paper?

• High-tech companies produce a lot of white papers, and many IT managers use them—even if no one can clearly explain what they are.

• Some generalizations:– Most white papers are around 10 letter-sized pages

with black & white illustrations. – They are written with an authoritative, neutral tone. – Most are distributed through the Web as PDFs. – They can take from 4 to 10 weeks and cost from

US$5,000 to US$30,000 to prepare.

Read the Art of the White Paper – uploaded to course materials

What is a White Paper?

• Google search for the phrase “white papers” generated 248,000,000 million hits!

• Most believe white papers to be a persuasive or informative (sometimes both!)

• A pre-sales document aimed at potential customers who have not yet made up their minds to buy a certain product or back a certain technology.

• A piece of marketing collateral whose form and content lies somewhere between a glossy brochure and a technical manual.

What is a White Paper?

• Google search for the phrase “white papers” generated 248,000,000 million hits!

• Most believe white papers to be a persuasive or informative (sometimes both!)

• A pre-sales document aimed at potential customers who have not yet made up their minds to buy a certain product or back a certain technology.

• A piece of marketing collateral whose form and content lies somewhere between a glossy brochure and a technical manual.

What is a White Paper?

Why Write a White Paper?• There are many reasons why a company may issue a white paper:

– To educate potential customers.– To educate the sales force (who may not fully understand the product

and its benefits).– To educate the media by providing a background document for a press

release or press conference. The media in turn will inform potential investors, potential customers, and the public.

– To be offered as free content to trade magazines or business publications. In this case, the white paper is usually signed by a senior executive.

– To be offered as a “fulfillment piece” in advertisements, direct mailings, and the Web (“Register here to receive a free white paper on...”). This helps gather leads for the sales force.

– To redefine the market or the “playing field.”– To help give the company an aura of credibility and authority in its

market.

What is a White Paper?

Who Reads White Papers?

• White papers are usually aimed at senior IT managers. White papers with a less technical focus are often aimed at CFOs, operations managers and other non-IT managers. Sometimes these people will make the decision to buy or not to buy the product in question.

• Sometimes they are “technical recommenders” who advise the decision-makers elsewhere in the company.

Who Reads White Papers?

• What is very clear is that managers actually read white papers. In fact, according to a recent survey of 2,500+ IT managers: – More than 3 out of 4 say they use white papers to get

preliminary information about products and vendors– 60% say they look at 1 white paper a month, while

75% look at 1 every 2 months.– 93% pass along white papers to others in their

organization, including 2 out of 3 who pass them to their higher-ups.

• To sum up, IT people read white papers when they’re interested in a new technology or need to select a technology for their organizations.

What is a Formal Report?

What is a Formal Report?

• The term report covers a wide variety of business documents.

• Letters, memos, and even email messages, for example, may be considered reports when they present essentially factual information in a highly organized way.

• Reports may be short (usually less than 10 pages), long (more than 10 pages—perhaps up to thousands of pages in bound volumes), informal or formal (based on writing and presentation style), informative (facts only) or analytical (facts plus analysis and recommendations).

What is a Formal Report?

• Because they are longer, more complex, and usually of greater importance to an organization, reports need to be prepared with greater care than is usually afforded most correspondence.

• The same basic writing skills apply, but reports are typically based on research. The report writer needs to understand the basic principles of research and how to interpret and present the results of that research in a readable, usable way.

What is a Formal Report?

• As a rule, one or more readers of the report will make a decision based on the information it presents, so report writers have a responsibility to ensure that the information and any recommendations presented will contribute to the best decision possible.

Understanding Types of Formal Reports

– Informational report: presents results– Analytical report: presents results and draws

conclusions– Recommendation report: presents results,

draws conclusions, and makes recommendations

– Often, reports come after a proposal and provide additional detail or progress updates

Analytical Reports Address Questions

• What is the best way to do Function X?

• What causes Situation X?

• What are the results of Situation X?

• Could we do Function X?

Recommendation Reports Address Questions

• What should we do about Problem X?

• Should we do Function X?

• Should we use Technology A or Technology B to do Function X?

• We currently use Method A to do Function X. Should we be using Method B?

Problem-Solving Model for Preparing Formal Reports

• Analyze your audience.• Analyze your purpose.• Identify questions that need to be answered.• Carry out appropriate research.• Draw conclusions from the research.• Formulate recommendations based on

conclusions.

Feasibility Reports Answer Three Kinds of Questions

• Questions of possibility

• Questions of economic wisdom

• Questions of perception

Steps in Preparing a Feasibility Report

– Identify the problem or opportunity.– Establish criteria for responding to the

problem or opportunity.– Determine the options.– Study each option according to the criteria.– Draw conclusions about each option.– Formulate recommendations based on the

conclusions.

Ways to Present Your Conclusions

• Rank all the options.

• Classify all the options in two categories: acceptable and unacceptable.

• Present a compound conclusion.

Typical Body Elements

• Introduction

• Methods

• Results

• Conclusions

• Recommendations

Questions to Consider in Writing Your Introduction

• What is the subject of the report?

• What is the purpose of the report?

• What is the background of the report?

• What are your sources of information?

• What is the scope of the report?

Questions to Consider in Writing Your Introduction

(cont.)

• What are the most significant findings?

• What are your recommendations?

• What is the organization of the report?

• What key terms are you using in the report?

Writing the Body of Your Report

• Methods. What did you do?

• Results. What did you see?

• Conclusions. What does it mean?

• Recommendations. What should we do?

Factors to Consider in Writing Recommendations

• Content

• Tone

• Form

• Location

Elements of the Front Matter

• Letter of transmittal

• Cover

• Title page

• Abstract

• Table of contents

• List of illustrations

• Executive summary

Types of Abstracts

• A descriptive abstract describes the kinds of information contained in the document.

• An informative abstract presents the major findings.

Guidelines for Writing an Executive Summary

• Use specific evidence in describing the background.

• Be specific in describing the research.

• Describe the methods briefly.

• Describe the findings according to your readers’ needs.

• Ask an outside reader to review your draft.

Elements of the Back Matter

• glossary and list of symbols

• references

• appendices

What is an Informal Report?

• E-mails

• Memos

• Forms

• Letters

• Reports

Informal reports can take many forms

Writing Process for Informal Reports

• Analyze your audience.

• Analyze your purpose.

• Research the subject and compile your information.

• Choose an appropriate format.

• Draft the report.

• Revise, edit, and proofread the report.

Writing Informal Reports for Multicultural Readers

– How might your readers react to your informal report?

– Will your readers be comfortable with your choice of document?

– Do you need to adjust your writing style?

Types of Informal Reports

• Directives

• Field and lab reports

• Progress and status reports

• Incident reports

• Meeting minutes

Field and Lab Reports

• Describe inspections, maintenance, and site studies

• Explain the problem, methods, results, and conclusions

• Deemphasize methods• Can include recommendations

Questions to Answer in a Field or Lab Report

– What is the purpose of the report?– What are the main points covered in the

report?– What were the problems leading to the

decision to perform the procedure?– What methods were used?– What were the results?– What do the results mean?– What should be done next?

Progress and Status Reports

• A progress report describes an ongoing project.

• A status report or activity report describes the entire range of operations of a department or division.

Reporting Your Progress Honestly

• Be honest in responding to common problems:– The deliverable won’t be what you thought it

would be.– You won’t meet your schedule.– You won’t meet the budget.

Organizational Patterns in Progress and Status Reports

Time Pattern Task Pattern

Discussion Discussion

A. Past Work A. Task 1

B. Future Work 1. Past Work

2. Future Work

B. Task 2

1. Past Work

2. Future Work

Appropriate Tone in a Progress or Status Report

• If the news is good, convey your optimism but avoid overstatement.

• Don’t panic if the preliminary results are not as promising as you had planned or if the project is behind schedule.

Writing Incident Reports

• Briefly summarize the accident.

• Present background information.

• Present your main conclusion about what caused the accident.

• Explain the root cause of the accident.

• State your recommendations.

Writing Meeting Minutes

• Record the logistical details of the meeting.• Record the purpose of the meeting.• Record the action taken at the meeting.• Be objective; do not interpret events.• Do not record emotional exchanges between

participants.

Designing a Set of Instructions

• What are your reader’s expectations?

• Do you need to create more than one set of instructions for different audiences?

• What languages should you use?

• Will the environment in which the instructions are read affect the document design?

Questions to Consider in Designing the Pages

• Should you make your pages multilingual?– Sequential or simultaneous?

What is a User Manual?

What is a User Manual?

• User manual – a document for users that explains how to use or operate something, such as a software program. Usually organized topically or by task.

Writing Process for Instructions and Manuals

• Analyze your audience and purpose.

• Gather and organize your information.

• Design the document.

• Draft the document.

• Revise, edit, and proofread the document.

• Conduct usability tests of the document.

Writing User Manuals

• Start here:– Deciding on the type of manual and its purpose– Analyzing the needs of the manual user– Deciding on critical content– Deciding on overall design– Creating your overview or roadmap– Writing the body of the manual (in plain English)

• Writing technical descriptions• Writing technical explanations• Writing technical instructions

– Creating glossaries and indexes– Using graphics effectively– Writing the troubleshooting section– Copyediting and proofreading your manual.

Questions to Consider in Designing the Pages

• Will readers be anxious about the information?– If the readers might find the information

intimidating, it’s your job to present it in an approachable format

– eg setting up a wireless network at home– http://

www.microsoft.com/windowsxp/using/networking/setup/wireless.mspx

Questions to Consider in Designing the Pages

• Will the environment in which the instructions are read affect the page design or typography?– Outdoors, in a lab, in a garage, with green eggs and

ham– Example – installing a car audio system

Designing Clear, Attractive Pages

• Create an open design.

• Clearly relate the graphics to the text.

• http://www.baddesigns.com/examples.html

Steps in Planning for Safety

• Write effective safety information.

• Design effective safety information.

• Place safety information in the appropriate location.

Signal Words in Safety Labels

• Danger: an immediate and serious hazard that will likely be fatal

• Warning: potential for serious injury or death or serious damage to equipment

• Caution: potential for anything from moderate injury to serious equipment damage or destruction

• Note: a tip or suggestion to help readers carry out the procedure successfully

Elements of Instructions

• Title• Table of Contents• Issue date/expiration date• General introduction• Step-by-step instructions• FAQs• Index• Conclusion

Forms of Titles for Instructions

Effective titles:• How-to. “How to Install the J112 Shock

Absorbers”• Gerund. “Installing the J112 Shock Absorber”

Ineffective titles: Noun strings.

“J112 Shock Absorber Installation Instructions”

Drafting Introductions for Instructions

– Who should carry out the task?– Why should the reader carry out this task?– When should the reader carry out this task?– What safety measures or other concerns

should the reader understand?– What items will the reader need?– How long will the task take?

Drafting Steps in Instructions

– Number the instructions.– Present the right amount of information in

each step.– Use the imperative mood.– Don’t confuse steps and feedback

statements.– Include graphics.– Do not omit the articles (a, an, the) to save

space.

• Who should use this manual?

• What product, procedure, or system does the manual describe?

• What is the manual’s purpose?

• What are the manual’s major components?

• How should the manual be used?

Front Matter of a Manual

Guidelines for Drafting the Body of a Manual

• Structure the body according to how the reader will use it.

• Write clearly.

• Be informal, if appropriate.

• Use graphics.

Planning Manuals for Multicultural Readers

– In what language should the information be written?

– Do the text or graphics need to be modified?– What is the reader’s technological

infrastructure?

Basic Principles of Usability Testing

• It permeates product development.

• It involves studying real users as they use the product.

• It involves setting measurable goals and determining whether the product meets them.

Planning a Usability Test

• Understand your users’ needs.• Determine the purpose of the test.• Staff the test team.• Set up the test environment.• Develop a test plan.• Select participants.• Prepare the test materials.• Conduct a pilot test.

Important Aspects of Conducting the Usability Test• Staying organized

• Interacting with the participant

• Debriefing the participant

Interpreting & Reporting the Data

• Tabulate the information.

• Analyze the information.

• Report the information.

• http://www.theusermanualsite.com