TECHNICAL WRITING AND THE WEB RAISING AWARENESS OF

TECHNICAL WRITING AND THE WEB WHAT IS TECHNICAL COMMUNICATION? One or more of the following characteristics 1

TECHNICAL WRITING AND THE WEB WHAT IS TECHNICAL COMMUNICATION? One or more of the following characteristics • Technical or specialized topics 2

TECHNICAL WRITING AND THE WEB WHAT IS TECHNICAL COMMUNICATION? One or more of the following characteristics • Technical or specialized topics • Uses technology 3

TECHNICAL WRITING AND THE WEB WHAT IS TECHNICAL COMMUNICATION? One or more of the following characteristics • Technical or specialized topics • Uses technology • How to do something 4

TECHNICAL WRITING AND THE WEB WHEN IS A WHITE PAPER CONSIDERED “TECHNICAL COMMUNICATION”? Examples from STC Website § Software instructions help users be more successful on their own, improving how easily those products gain acceptance into the marketplace and reducing costs to support them. 5

TECHNICAL WRITING AND THE WEB WHEN IS A WHITE PAPER CONSIDERED “TECHNICAL COMMUNICATION”? Examples from STC Website § Functional specifications and proposals help one group of technical experts communicate effectively with other technical experts, speeding up development cycles, reducing rework caused by misunderstandings, and eliminating risks associated with miscommunication. 6

TECHNICAL WRITING AND THE WEB WHEN IS A WHITE PAPER CONSIDERED “TECHNICAL COMMUNICATION”? Examples from STC Website § Technical illustrations clarify steps or identify the parts of a product, letting users focus on getting their task done quickly or more accurately. 7

TECHNICAL WRITING AND THE WEB WHEN IS A WHITE PAPER CONSIDERED “TECHNICAL COMMUNICATION”? Examples from STC Website § Usability studies uncover problems with how products present themselves to users, helping those products become more user friendly. 8

TECHNICAL WRITING AND THE WEB STYLISTIC PRINCIPLES FOR COMPUTER DOCUMENTATION § Time is a valuable commodity § Readers are worldwide 9

TECHNICAL WRITING AND THE WEB STYLISTIC PRINCIPLES FOR COMPUTER DOCUMENTATION Write simply, directly, and accurately 10

TECHNICAL WRITING AND THE WEB STYLISTIC PRINCIPLES FOR COMPUTER DOCUMENTATION Write simply, directly, and accurately § Avoid humor 11

TECHNICAL WRITING AND THE WEB STYLISTIC PRINCIPLES FOR COMPUTER DOCUMENTATION Write simply, directly, and accurately § Avoid humor § Avoid jargon 12

TECHNICAL WRITING AND THE WEB STYLISTIC PRINCIPLES FOR COMPUTER DOCUMENTATION Write simply, directly, and accurately § Avoid humor § Avoid jargon § Be consistent 13

TECHNICAL WRITING AND THE WEB STYLISTIC PRINCIPLES FOR COMPUTER DOCUMENTATION Write simply, directly, and accurately § Avoid humor § Avoid jargon § Be consistent § Anticipate a reader’s questions 14

TECHNICAL WRITING AND THE WEB MEDIUM TO CONVEY THIS KNOWLEDGE IN 2011: THE WEB The Yahoo Style Guide 15

TECHNICAL WRITING AND THE WEB MEDIUM TO CONVEY THIS KNOWLEDGE IN 2011: THE WEB The Yahoo Style Guide § Shape your text for online reading. 16

TECHNICAL WRITING AND THE WEB MEDIUM TO CONVEY THIS KNOWLEDGE IN 2011: THE WEB The Yahoo Style Guide: § Shape your text for online reading. § Get to the point. 17

TECHNICAL WRITING AND THE WEB MEDIUM TO CONVEY THIS KNOWLEDGE IN 2011: THE WEB The Yahoo Style Guide: § Shape your text for online reading. § Get to the point. § Make text easy to scan. 18

TECHNICAL WRITING AND THE WEB MEDIUM TO CONVEY THIS KNOWLEDGE IN 2011: THE WEB The Yahoo Style Guide: § Shape your text for online reading. § Get to the point. § Make text easy to scan. § Write for the world. 19

TECHNICAL WRITING AND THE WEB MEDIUM TO CONVEY THIS KNOWLEDGE IN 2011: THE WEB The Yahoo Style Guide: § Shape your text for online reading. § Get to the point. § Make text easy to scan. § Write for the world. § Help people navigate. 20

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (CONCEPTS) How do people read material online? 21

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (CONCEPTS) People scan text on computer screens, not read text 22

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (CONCEPTS) Scan text on computer screens § Highlighted keywords (hypertext, typeface) 23

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (CONCEPTS) Scan text on computer screens § Highlighted keywords (hypertext, typeface) § Meaningful subheadings (not clever subheadings) 24

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (CONCEPTS) Scan text on computer screens § Highlighted keywords (hypertext, typeface) § Meaningful subheadings (not clever subheadings) § Bulleted lists 25

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (CONCEPTS) Scan text on computer screens § Highlighted keywords (hypertext, typeface) § Meaningful subheadings (not clever subheadings) § Bulleted lists § One idea per paragraph 26

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (CONCEPTS) Scan text on computer screens § Highlighted keywords (hypertext, typeface) § Meaningful subheadings (not clever subheadings) § Bulleted lists § One idea per paragraph § Inverted pyramid style, starting with the conclusion (journalistic style) 27

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (CONCEPTS) 28 Scan text on computer screens § Highlighted keywords (hypertext, typeface) § Meaningful subheadings (not clever subheadings) § Bulleted lists § One idea per paragraph § Inverted pyramid style, starting with the conclusion (journalistic style) § Half the word count (or less) than conventional writing

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (WRITING AND PRESENTATION STYLE) Research with 5 versions of the same website with different wording shows improvements in performance measures: § Time § Errors § Memory § Site structure 29

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (WRITING AND PRESENTATION STYLE) Original Version § Nebraska is filled with internationally recognized attractions that draw large crowds of people every year, without fail. In 1996, some of the most popular places were Fort Robinson State Park (355, 000 visitors), Scotts Bluff National Monument (132, 166), Arbor Lodge State Historical Park & Museum (100, 000). Carhenge (86, 598), Stuhr Museum of the Prairie Pioneer (60, 002), and Buffalo Bill Ranch State Historical Park (28, 446). 30

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (WRITING AND PRESENTATION STYLE) Combined Version (Uses all three style improvements) In 1996, six of the most-visited places in Nebraska were: § Fort Robinson State Park § Scotts Bluff National Monument § Arbor Lodge State Historical Park & Museum § Carhenge § Stuhr Museum of the Prairie Pioneer § Buffalo Bill Ranch State Historical Park 31

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (WRITING AND PRESENTATION STYLE) Four performance measures (time, errors, memory, and site structure): § Concise: 58% improvement § Scannable layout: 47% improvement § Objective language: 27% § Combined version: 124% improvement (No improvement percentage listed for site structure, as it is not relevant to one page. ) 32

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (INVERTED PYRAMID) § Readers scan from the top. The inverted pyramid style gives the reader results faster. § Pyramid Style § Most research papers and engineering reports open with a problem statement, then review the prior art, and move into a detailed discussion of the different options that are considered and the methods that are used. After plowing through twenty pages of basics the patient reader may find a section entitled results with detailed tables, charts, and statistical tests; and after an additional five pages of this, a page or so of conclusions is reached. 33

TECHNICAL WRITING AND THE WEB SHAPE YOUR TEXT FOR ONLINE READING (INVERTED PYRAMID) § Readers scan from the top. The inverted pyramid style gives the reader results faster. § Inverted Pyramid Style § Journalists have long adhered to the inverse approach: start the article by telling the reader the conclusion ("After long debate, the Assembly voted to increase state taxes by 10 percent"), follow by the most important supporting information, and end by giving the background. 34

TECHNICAL WRITING AND THE WEB GET TO THE POINT Your white paper has three seconds or less to catch someone’s attention 35

TECHNICAL WRITING AND THE WEB GET TO THE POINT Your white paper has three seconds or less to catch someone’s attention § Keep it short. 36

TECHNICAL WRITING AND THE WEB GET TO THE POINT Your white paper has three seconds or less to catch someone’s attention § Keep it short. § Front-load your content. 37

TECHNICAL WRITING AND THE WEB GET TO THE POINT Your white paper has three seconds or less to catch someone’s attention § Keep it short. § Front-load your content. § Keep it simple. 38

TECHNICAL WRITING AND THE WEB GET TO THE POINT It is harder to get to the point than to ramble 39

TECHNICAL WRITING AND THE WEB GET TO THE POINT It is harder to get to the point than to ramble § Elfdragonlord (question): § However I have a major problem with writing short stories. Whenever I come up with a good idea for a story, try as I might to keep it simple, the plot always ends up unraveling into something too complex and involved to obey the word limit of a short story. I find it hard to write anything engaging or interesting (i. e. worth reading) that doesn't involve too many places, too much information, too much background, too many twists and turns or whatever to be contained within a short story format. 40

TECHNICAL WRITING AND THE WEB GET TO THE POINT It is harder to get to the point than to ramble § Max Vantage (response): § Bear with me when I say this as I don't mean to sound rude or that I'm pointing my finger, but it sounds as if you lack discipline. I say this because, as you say, "the plot of your stories always ends up unraveling into something too complex". 41

TECHNICAL WRITING AND THE WEB GET TO THE POINT It is harder to get to the point than to ramble § Max Vantage (response continued): § This implies to me that you write straight away based only on fragments of an idea without having explored much about it, such as theme or moral of the story. The theme grounds your story into a single allimportant idea. Without it you could end up invading your proposed story with more and become overwhelmed such as you are suggesting now. 42

TECHNICAL WRITING AND THE WEB GET TO THE POINT What question does your white paper answer? 43

TECHNICAL WRITING AND THE WEB GET TO THE POINT What question does your white paper answer? Is this question reasonable for a white paper format? 44

TECHNICAL WRITING AND THE WEB GET TO THE POINT What question does your white paper answer? Is this question reasonable for a white paper format? § If some information or statement answers the question, keep it in the paper. 45

TECHNICAL WRITING AND THE WEB GET TO THE POINT What question does your white paper answer? Is this question reasonable for a white paper format? § If some information or statement answers the question, keep it in the paper. § If some information or statement does not answer the question, get rid of it. 46

TECHNICAL WRITING AND THE WEB GET TO THE POINT These are the standard journalism questions to answer when writing: 47

TECHNICAL WRITING AND THE WEB GET TO THE POINT These are the standard journalism questions to answer when writing: § Who? 48

TECHNICAL WRITING AND THE WEB GET TO THE POINT These are the standard journalism questions to answer when writing: § Who? § What? 49

TECHNICAL WRITING AND THE WEB GET TO THE POINT These are the standard journalism questions to answer when writing: § Who? § What? § When? 50

TECHNICAL WRITING AND THE WEB GET TO THE POINT These are the standard journalism questions to answer when writing: § Who? § What? § When? § Where? 51

TECHNICAL WRITING AND THE WEB GET TO THE POINT These are the standard journalism questions to answer when writing: § Who? § What? § When? § Where? § Why? 52

TECHNICAL WRITING AND THE WEB GET TO THE POINT Anticipate what question or questions your reader wants answered. 53

TECHNICAL WRITING AND THE WEB GET TO THE POINT Anticipate what question or questions your reader wants answered. Only answer that question or those questions in your paper. 54

TECHNICAL WRITING AND THE WEB MAKE TEXT EASY TO SCAN Here are some guidelines to make your text easy to scan: 55

TECHNICAL WRITING AND THE WEB MAKE TEXT EASY TO SCAN Here are some guidelines to make your text easy to scan: § Meaningful headlines and subheading 56

TECHNICAL WRITING AND THE WEB MAKE TEXT EASY TO SCAN Here are some guidelines to make your text easy to scan: § Meaningful headlines and subheading § Bulleted lists 57

TECHNICAL WRITING AND THE WEB MAKE TEXT EASY TO SCAN Here are some guidelines to make your text easy to scan: § Meaningful headlines and subheading § Bulleted lists § Tables 58

TECHNICAL WRITING AND THE WEB MAKE TEXT EASY TO SCAN Here are some guidelines to make your text easy to scan: § Meaningful headlines and subheading § Bulleted lists § Tables § Short paragraphs 59

TECHNICAL WRITING AND THE WEB MAKE TEXT EASY TO SCAN Here are some guidelines to make your text easy to scan: § Meaningful headlines and subheading § Bulleted lists § Tables § Short paragraphs § Bold text 60

TECHNICAL WRITING AND THE WEB MAKE TEXT EASY TO SCAN Here are some guidelines to make your text easy to scan: § Meaningful headlines and subheading § Bulleted lists § Tables § Short paragraphs § Bold text § Pull quotes 61

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD We write using US English. 62

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD We write using US English. We need to be understood around the world. 63

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD Do the following: 64

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD Do the following: § Always use the simplest and most specific word possible. 65

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD Do the following: § Always use the simplest and most specific word possible. § Use one term for one concept and use terms consistency. 66

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD Do the following: § Always use the simplest and most specific word possible. § Use one term for one concept and use terms consistency. § Do not use similar terms to mean subtly different things. 67

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD Do the following: § Always use the simplest and most specific word possible. § Use one term for one concept and use terms consistency. § Do not use similar terms to mean subtly different things. § Reserve “accessibility” to refer to features that support users with disabilities. 68

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content 69

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid noun and verb phrases. 70

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid noun and verb phrases. § Use “ensure” (or “verify”) instead of “make sure. ” 71

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid participial forms of verbs and also nouns formed from verbs. 72

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid participial forms of verbs and also nouns formed from verbs. § Use “arrive” instead of “be arriving” (am arriving, are arriving). 73

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid using words for something other than their literal meaning. 74

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid using words for something other than their literal meaning. § Do not use “what’s hot” unless you are talking about temperature. 75

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid abbreviations and acronyms that include other abbreviations and acronyms. 76

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid abbreviations and acronyms that include other abbreviations and acronyms. § Do not use “Gbps” for “Gb/sec” 77

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid contractions. 78

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Be careful of words than can be read as both verbs and nouns. 79

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Be careful of words than can be read as both verbs and nouns. § Read this manual. § This manual is a good read. 80

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Be careful of words than can be read as both verbs and nouns. § File § Post § Input § Screen § Word § Map 81

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Follow the rules of capitalization for standard written English. 82

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Follow the rules of capitalization for standard written English. § Do not capitalize the words that make up an abbreviation, even if the abbreviation is capitalized (except for proper nouns): ‒ Original equipment manufacturer ‒ OEM 83

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid culturally sensitive terms. 84

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid culturally sensitive terms. 85

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Whenever possible, use the central meaning of a word. 86

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Whenever possible, use the central meaning of a word. § Non-IT example—”Cage” ‒ Standard meaning: Enclosure to keep an animal ‒ Motorcycle Community: Another term for automobile (ride in a metal cage) ‒ Basketball: The basketball court (originally, professional basketball games were played in a cage to keep the ball inbounds all the time) Different sentence meaning based on context: “I passed 10 cages driving on the Steven’s Pass Highway on the way to Wenatchee. “ 87

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Avoid verbs with many meanings. § When unavoidable, use context to make your meaning unmistakable. 88

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § Follow these guidelines to globalize your content § Include optional hyphens in compound words and following prefixes where ambiguity would result. ‒ There are exceptions to this, such as “email. ” 89

TECHNICAL WRITING AND THE WEB WRITE FOR THE WORLD § These are guidelines, not unbreakable rules. § There may be times not to follow a guideline, but choose your battles carefully and with justification. 90

TECHNICAL WRITING AND THE WEB REMEMBER OUR READERS WHEN WRITING YOUR DOCUMENTS § Time is a valuable commodity § Readers are worldwide 91

TECHNICAL WRITING AND THE WEB WORKS CITED 92 § Barr, Chris, and the Senior Editors of Yahoo. The Yahoo Style Guide: The Ultimate Sourcebook for Writing, Editing, and Creating Content for the Digital World. First Edition: July 2010. New York, New York: St. Martin's Griffin, 2010. § Brook, James, et al. Read Me First! A Style Guide for the Computer Industry. Edited by Martyak. Mountain View, California: Sunsoft Press, 1996. § Creative Writing Forums. I find short stories annoyingly difficult to write. 01 27, 2007. http: //www. writingforums. org/archive/index. php/t-2183. html (accessed 10 26, 2011). § Microsoft Corporation Editorial Style Board. Microsoft Manual of Style for Technical Publications. Third. Edited by Kristine Haugseth and Sandra Haynes. Redmond, Washington: Microsoft Press, 2004. § Nielsen, Jacob. Alertbox: Inverted Pyramids in Cyberspace. June 1996. http: //www. useit. com/alertbox/9606. html (accessed 10 12, 2011). § Nielsen, Jakob. Alertbox: How Users Read on the Web. October 1, 1997. http: //www. useit. com/alertbox/9710 a. html (accessed October 10, 2011). § Society for Technical Communications. "Defining Technical Communications. " About STC. 2011. http: //stc. org/about-stc/the-profession-all-about-technical-communication/defining-tc (accessed October 11, 2011).

TECHNICAL WRITING AND THE WEB 93