Technical White Papers


Published on

Types of white papers, using IMRaD structure in a technical white paper, write-up usability test findings in a technical white paper. Slides are for students in my technical writing course.

Published in: Education, Technology, Business
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Technical White Papers

  1. 1. Technical White Papers • About white papers. • Importance of document design. • Structured authoring. • Writing the sections of your white paper. 1 English 317: Technical Writing © 2015 Karen L. Thompson  Department of English University of Idaho
  2. 2. Social or Political Focus • The term white paper was originally used to describe a report that states the social or political position of an organization. 2
  3. 3. IT Marketing Focus • Sometimes a white paper is a marketing document aimed at selling a certain technology or products. 3
  4. 4. Technical or Research White Papers • At other times, a white paper presents the results scientific research or findings from a usability test of a product(s). This is the type of white paper you are writing. 4
  5. 5. White Papers Can Be • Written for internal audiences – coworkers, project managers, high-level decision makers. OR • Written for external audiences – clients or customers. • In both cases, document design is important. 5
  6. 6. The Importance of Document Design • Document design supports (or can work against) the brand personality of a business or organization. • Enforcing a consistent document design has traditionally been done by giving employees style guides and having editors make certain that the style is consistently maintained. • In today’s workplace, however, the volume and complexity of documents means that traditional methods are often very inefficient. 6
  7. 7. Here’s an Example 7 • This is a list of the literature that Schweitzer Engineering Laboratories (SEL) produces. Under each menu item are often up to a hundred or more documents. • Because many different employees will write this literature, SEL needs to have a means of ensuring that those documents will be consistent in design, reflecting their brand, and also a way to do this efficiently. • Structured authoring provides the means of doing both.
  8. 8. Structured Authoring Technology • When writers use structured authoring technology, they complete a series of steps within a writing environment controlled by software that enforces style rules and organizing patterns for sets of documents. • Writers must complete these steps by using the software before the document can be published. • What this also means is that content can be easily separated and stored in a database, and then repurposed when creating documents that will use similar language for similar sections. 8
  9. 9. Adobe FrameMaker is a Popular Software for Structured Authoring 9 Most white papers are produced using structured authoring. Let’s look at an example.
  10. 10. 10 Notice how tableau’s website and white papers have a common look and feel. There is some variation in the pages of these white papers, but the design and structure is consistent.
  11. 11. These are examples of data sheets by SEL. These sheets describe the features and benefits of the products. Notice they have a consistent look and feel that supports the brand.
  12. 12. In this project, • You will not be using structured authoring technology, but you will be able to practice structured authoring conceptually. • I’ll provide a rule for the structure of your white paper that you should follow. • The design, however, will be your choice. 12
  13. 13. The Structure Rule is Based on IMRaD IMRaD stands for: – Introduction – Methods – Results and – Discussion 13 This is a common structure for presenting the results of research, and it evolved out of the need to separate: • Methods: how the research was done. • Results: what the research found. • Discussion: what the findings mean. Using this structure allows readers to decide the validity of methods, findings, and interpretation.
  14. 14. Structure Rule: Use Either IMRaD or Modified IMRaD Structure • Title Page • Table of Contents • Introduction • Methods • Results/Discussion • Conclusion and/or Recommendations • Bibliography 14 These major headings need to be in your paper. You may modify the IMRaD structure to put results and discussion together or separate them if that works best for your content. You will also need a clear conclusion and/or recommendations and a works cited or bibliography depending on the documentation style you are using. As you create the document design, remember to apply design principles you learned when composing the infographic.
  15. 15. Title Page: Poor Design Choices 15 Color choices and design elements convey meaning. Clearly, these are not the best rhetorical design choices.
  16. 16. Title Page: Improved Design Choices 16 These rhetorical design choices match the purpose of the white paper, so the design is supporting purpose.
  17. 17. Writing the Sections of Your White Paper 17
  18. 18. Word: Title Page Tip • If you change the background color of the title page (or any page) in Word, that background color will be in all pages. • To avoid that problem, use a text box, and stretch it the width and length of your cover page. • NOTE: there are other solutions to that problem. 18
  19. 19. How Introductions to Usability White Papers Function • Rhetorically, the introduction creates a permanent record of what was tested, why, who did the test, and for whom. – It’s important to be specific in defining/describing the products you tested and typical users of these products. 19
  20. 20. Rhetorical Moves for Writing the Introduction. Option 1: Start the introduction with a purpose statement. Example: This white paper describes the findings from a usability test of two free blogging tools: Tumblr and Blogger. Example: This white paper evaluates how Gimp, a free cloud computing tool, compares to its pricey counterpart: Adobe Photoshop. 20
  21. 21. Option 2: Start the introduction with phrase or sentence definition then move to a purpose statement. Example: Weebly and WordPress are [write a phrase or sentence-definition of these two tools]. This white paper describes the findings from a usability test of these two products. Another Example: Sometimes the phrase that defines the tool can be first, leading to a statement about the tools. Image editing software such as Adobe Photoshop often have steep learning curves, deterring most novices from trying them. This white paper describes the findings from a comparison of two image editing products aimed at novice users: [name the two products]. • Make a decision about which rhetorical move to make in your introduction based on audience analysis. What do they know? What do they need to know? 21
  22. 22. Introduction: other content to include. • Description of users you identified. If the user description is complex, then you might consider moving the level of detail to the methods section, and just briefly describe users in the introduction. • Add who did the testing and why. Use first person “I” because third person can sound pretty weird. If you include this project in your portfolio, you will want to make it clear that the usability test was done as part of course work in technical writing. 22
  23. 23. How Methodology Sections in Usability White Papers Function • Just as in an engineering or scientific experiment, the methodology section explains the design of the test or experiment. Rhetorically, it is how you did the test. • As such, it needs to include all aspects of methods. One mistake that novice writers make is to put introductory material into the methodology section and vice versa. • Scientific and engineering documents (and usability tests) often use an IMRaD structure because the reader needs these sections to be separate in order to evaluate the significance of the data. For example, was the test methodology valid, but the results were inconclusive? Were the results valid but the interpretation (discussion section) over-valuing the significance of the findings? 23
  24. 24. Methodology Section What to include. • Tasks. Describe the specific tasks you did when using each product. Consider using a list here. • Test Environment. State when you did the test, where, and anything else that helps a reader understand the testing methods you used such as type of computer (laptop, desktop, PC or Mac etc.?). • Evaluative Criteria/Rating Scale. State the criteria and Likert Scale used to evaluate usability. 24
  25. 25. How Results Sections Function 25 • Digest the Data (Findings) for Readers – What this means: – In one study comparing successful and unsuccessful engineering reports, engineers and managers frequently referred to "digested" vs. "undigested" data. – Successful engineers not only reported technical information but helped their readers understand the significance of the data. • You will want to do the same with your raw data.
  26. 26. Writing the Results • Analyze the raw data from your data collection form. Decide the most significant aspects of the test findings. • Turn the notes you took into clear, concise technical descriptions of what happened when you did the task and how you evaluated usability (i.e. criteria and Likert Scale scores). • Organize the results section to help readers understand the significance of the findings (see slide 17 for one way to organize findings -- there are other ways than this, make a decision based on what you are testing) • Incorporate visuals to help reader follow the test findings: – screenshots and/or graphics to represent some of the test findings such as significant aspects of the Likert Scale rankings. 26
  27. 27. Ways to Organize Test Results The following slide explains one way to organize test results. NOTE: There are many ways to organize test results based on what makes sense for what you tested and your usability test data. 27
  28. 28. Here is one way to organize the results. Use complete criteria statements with Likert Scale in the results section. • Task 1: Create a web site and assign a theme. [List each task and describe what happened when you did the task. Include screenshots as needed. End your description with the criteria statement and Likert Scale with score.] [Insert criteria statement used to evaluate usability.] 28 5 At the end of your results section, compare scores earned per criteria statement for each product. You could graphically represent the scoring data in a table or bar chart. List each criteria statement you applied with the corresponding score. See usability testing lecture for information on criteria statements and Likert Scales.
  29. 29. Recommendations • Make recommendations to potential users of the product. Consider if it is useful to explain which product might be best for a novice vs. a product for a more experienced user. • NOTE: if both are about equal, then say that. 29