Chapter 19 user manuals

Uploaded on

test lecture for jhu

test lecture for jhu

More in: Education
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads


Total Views
On Slideshare
From Embeds
Number of Embeds



Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

    No notes for slide


  • 1. Instructions and Manuals White PapersFormal and Informal Reports Some info from Markel - Chapter 19, mostly from Talalay
  • 2. First Things First• What is the difference between an abstract and an executive summary?
  • 3. Abstract v Executive Summary DefinitionsAbstract 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 papers 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, its 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.
  • 4. What is a White Paper?
  • 5. 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
  • 6. 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.
  • 7. 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.
  • 8. What is a White Paper?
  • 9. 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.
  • 10. What is a White Paper?
  • 11. 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.
  • 12. 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.
  • 13. What is a Formal Report?
  • 14. 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).
  • 15. 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.
  • 16. 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.
  • 17. 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
  • 18. 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?
  • 19. 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?
  • 20. 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.
  • 21. Feasibility Reports Answer Three Kinds of Questions• Questions of possibility• Questions of economic wisdom• Questions of perception
  • 22. 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.
  • 23. Ways to Present Your Conclusions• Rank all the options.• Classify all the options in two categories: acceptable and unacceptable.• Present a compound conclusion.
  • 24. Typical Body Elements• Introduction• Methods• Results• Conclusions• Recommendations
  • 25. 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?
  • 26. 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?
  • 27. 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?
  • 28. Factors to Consider in Writing Recommendations• Content• Tone• Form• Location
  • 29. Elements of the Front Matter• Letter of transmittal• Cover• Title page• Abstract• Table of contents• List of illustrations• Executive summary
  • 30. Types of Abstracts• A descriptive abstract describes the kinds of information contained in the document.• An informative abstract presents the major findings.
  • 31. 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.
  • 32. Elements of the Back Matter• glossary and list of symbols• references• appendices
  • 33. What is an Informal Report?
  • 34. Informal reports can take many forms• E-mails• Memos• Forms• Letters• Reports
  • 35. 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.
  • 36. 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?
  • 37. Types of Informal Reports• Directives• Field and lab reports• Progress and status reports• Incident reports• Meeting minutes
  • 38. Field and Lab Reports• Describe inspections, maintenance, and site studies• Explain the problem, methods, results, and conclusions• Deemphasize methods• Can include recommendations
  • 39. 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?
  • 40. 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.
  • 41. 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.
  • 42. Organizational Patterns in Progress and Status ReportsTime Pattern Task PatternDiscussion 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
  • 43. 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.
  • 44. 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.
  • 45. 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.
  • 46. 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?
  • 47. Questions to Consider in Designing the Pages• Should you make your pages multilingual? – Sequential or simultaneous?
  • 48. What is a User Manual?
  • 49. 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.
  • 50. 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.
  • 51. 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.
  • 52. 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://
  • 53. 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
  • 54. Designing Clear, Attractive Pages• Create an open design.• Clearly relate the graphics to the text.• http://
  • 55. Steps in Planning for Safety• Write effective safety information.• Design effective safety information.• Place safety information in the appropriate location.
  • 56. 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
  • 57. Elements of Instructions• Title• Table of Contents• Issue date/expiration date• General introduction• Step-by-step instructions• FAQs• Index• Conclusion
  • 58. Forms of Titles for InstructionsEffective 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”
  • 59. 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?
  • 60. 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.
  • 61. Front Matter of a Manual• 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?
  • 62. 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.
  • 63. 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?
  • 64. 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.
  • 65. 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.
  • 66. Important Aspects ofConducting the Usability Test• Staying organized• Interacting with the participant• Debriefing the participant
  • 67. Interpreting & Reporting the Data• Tabulate the information.• Analyze the information.• Report the information.
  • 68. •