What is Technical writing style

what is technical writing and reporting and what is technical writing and communication how technical writing is different from general writing
Dr.DaisyWatson Profile Pic
Dr.DaisyWatson,France,Professional
Published Date:03-07-2017
Your Website URL(Optional)
Comment
Writing Writing Writing Writing Writing That That That That That W Works orks Works W Works orks A Teacher’s Guide to Technical Writing by Dr. Steven M. Gerson Johnson County Community College Developed and Published by: Kansas Curriculum Center Washburn University Topeka, KS Table of Preface ...................................................................................... i-ii Contents Chapter One: Why Teach Technical Writing ........................... 1-9 Definition ............................................................................ 1 Rationale .......................................................................... 2-3 Communication Continuum ............................................. 4-5 Technical Writing vs. Essays ............................................... 6 Five Components of Technical Writing ............................. 7-8 End of Chapter Activities .....................................................9 Chapter Two: Five Traits of Technical Writing ..................... 10-25 Clarity .......................................................................... 10-12 Conciseness ................................................................. 13-16 Accessibility ................................................................. 16-17 Audience Recognition .................................................. 18-19 Accuracy ........................................................................... 20 Five Trait Rubric .................................................................21 End of Chapter Activities .............................................. 22-25 Chapter Three: Applications of Technical Writing ............... 26-80 Letters .......................................................................... 26-33 Memos ......................................................................... 34-38 E-Mail ........................................................................... 39-42 Reports ......................................................................... 43-45 The Job Search ............................................................. 46-54 Instructions ................................................................... 54-57 Web Pages ................................................................... 58-62 PowerPoint Presentations ............................................. 63-65 Brochures ..................................................................... 66-69 Newsletters .................................................................. 70-74 Fliers ............................................................................ 75-78 Graphics ....................................................................... 79-80 Chapter Four: Technical Writing Assignments ..................... 81-96 Sales Letters ....................................................................... 81 Letters of Inquiry ............................................................... 82 Memos ......................................................................... 82-83 E-Mail ........................................................................... 83-84 Reports ......................................................................... 84-85 The Job Search .................................................................. 85 Instructions ........................................................................ 86 Web Pages and PowerPoint .......................................... 86-87 Brochures/Newsletters .................................................. 87-88 Fliers ................................................................................. 88 Grouped Assignments .................................................. 89-90 Conclusion ........................................................................ 91 Sample Technical Writing I ................................................ 91 Sample Course Scope and Sequence ............................ 92-96 Chapter One Technical Writing: A Definition Technical writing is commu- nication written for and Why Teach about business and industry, focusing on products and Technical Writing? services: how to manufac- ture them, market them, manage them, deliver them, and use them. Technical writing is written: in the work environment (in the office, from 8:00 to 5:00, not counting overtime) for supervisors, col- leagues, subordinates, vendors, and customers Technical writing, which must be understood easily and quickly, includes: memos and e-mail letters reports Why is technical writing so important? instructions brochures and newsletters Why would I want to teach technical writing? the job search Don’t I have enough to teach now without adding one more web pages assignment or series of assignments to my curriculum? fliers PowerPoint presentations What’s the point? graphics Technical writing is not literature; it’s neither prose which recounts the fictional tales of characters nor poetry which expresses deeply felt, Technical writing is the universal emotions through similes and metaphors. resumé that helps get a Technical writing is neither an expressive essay narrating an job and the web page occurrence nor an expository essay analyzing a topic. that promotes a Technical writing is not journalism, written to report the news. company. Technical writing does not focus on poetic images, describe personal In each case, the experiences, or report who won the basketball game. technical document Instead, technical writing is: must be quantifiable, —an instructional manual for repairing machinery precise, and easily —a memo listing meeting agendas —a letter from a vendor to a client understood. —a recommendation report proposing a new computer system 1 Once students are employed, will they have to write on the job? The answer is a resounding YES One reason for teaching technical writing is so students will know the types of documents they will write on the job. When our students are employed and have to write on the job, will they write essays? The answer is no. Our students, when employed, will not write essays at work. They will write essays while working on their college degrees; they might even be asked to write an essay on their job application when Students often do applying for work. However, once the job begins, essays end. not believe they will have to write What takes the place of the essay? at work; they assume that once The answer is technical writing—memos, letters, reports, e-mail, proposals, instructions, even web pages. That’s why technical writing is their education is important. Technical writing is the type of written communication that completed, our students will be responsible for on the job. writing will be a distant memory. Is technical writing a necessary component of They are wrong. every employee’s professional skill? Daily, newspapers tell us that employers want to hire people who can communicate effectively, both in writing and orally. Career counselors reiterate this. In fact, we are told that on the job, an employee will spend at least 20 percent of his or her time writing. This number increases as an employee’s responsibilities increase. Managers spend up to 50 percent of their time writing. CEOs spend between 80 and 100 percent of their work week communicating. 2 How does technical writing compare/contrast to traditional essays? Technical writing is different from other types of written communication. Does that mean, therefore, that you must relearn all your teaching skills to accommodate this new communication beast? Absolutely not. Many of the writing skills you already teach are applicable to technical writing. Others are less valid. “Technical writing would come in handy for some students, such as our vo-tech kids. When they enter the job market, they could benefit by knowing how to write at work. But what about our college-bound students? Why would they need technical writing?” Here is a reminder… College lasts only four to six years. In K-12, we should continue On the next to prepare our students for college by teaching essays. In addition, we should prepare them for what comes next—their jobs. After page is a they graduate with their AA or BA or BS, they go to work where Communication they will write memos, letters, and reports. Continuum The career and technical education students—the students who including traits will work as mechanics, welders, office help, or daycare center assistants—can benefit by learning how to write technical and examples documents. of five types of However, our students who acquire associate degrees and bachelor writing, ranging degrees—the students who go on to become computer programmers, CAD/CAM operators, dental hygienists, fashion from the merchandising specialists, graphic artists, engineers, architects, connotative accountants, doctors, and lawyers—also will need to write memos, letters, and reports. to the denotative. 3 Communication Continuum Connotative/Expressive Type of Examples Traits Writing Connotative and expressive Creative Poems, plays, stories words, fictional characters, Writing imagery, and plots Subjective, based on Expressive personal experience, Narratives, descriptions connotative and expressive Writing words Comparison/contrast, Objective, connotative and Expository denotative words analysis, cause/effect, Writing argument/persuasion Objective, written from factual observation, short News stories, features, Journalism sentences and paragraphs, editorials some connotative but more denotative words Memos, letters, reports, Objective, written about products or services, short instructions, resumés, Technical web pages sentences and paragraphs, Writing denotative words Denotative/Objective Legend: Connotative Denotative On the next page is a poem about a tennis Of course, there are exceptions… shoe as well as Newsletters, sales letters, websites, and fliers might technical specifications include promotional information. Such sales details for manufacturing the same shoe. could depend on expressive words—maybe even These two writing fictional characters. However, generally speaking, samples further illustrate most technical writing is denotative the difference between versus connotative. technical writing and other types of writing. 4 Technical Specifications for Ode to a Shoe Manufacturing Tennis Shoes My son’s tennis shoes rest temporarily in a The D40 Slammer Tennis Shoe will be heap against the kitchen door, manufactured to the following specifications: their laces soiled, their tongues hanging out like exhausted terriers. Sole: Neoprene rubber 345 The soles, worn down on the insides from white enameled paint sliding into second, 1.589" high are green, the shades of summer. Slammer waffle-textured© Canvas exteriors, once pristine white, are the Uppers: Blue canvas colors of the rainbow— Tongue: White canvas sun bleached, mud splattered, rained on, Oval Slammer© logo heat- ketchup and mustard adorned, pressure sealed, centered .50" each shoe shouting a child’s joyous from all sides exuberance: “I’m alive” Laces: 15" long 100% cotton Aglets: Clear polyacetate plastic 290 Weight: 1 lb. 6 oz. “Unclear writing costs American businesses real money—over one billion dollars a year, according to one estimate…Did you know the Three Mile Island nuclear power plant meltdown was The graphic partly attributed to poorly appearing on written procedures?” the next page (“Why Dick and Jane Can’t Write on the Job…and How to Help Them,” Janet Van Wicklen, American Society of Training and Development, 2000). examines how technical writing “The ability to communicate compares and effectively is the most important skill contrasts you can have, whether you’re giving to essays. speeches, pitching ideas to your boss, or simply sending off an e-mail or leaving a voice message.” (“What You Need to Know About Career Planning,” http://careerplanning.about.com/cs/importantskills/2002.) 5 Comparison/Contrast: Technical Writing vs. Essays Components Technical Writing Essays Summary Uses examples, anecdotes, Uses examples, Development testimony, data, research anecdotes, Same for both testimony, data, research It is important It is important Grammar Same for both Provides an introduction, Provides an body, and conclusion introduction, Uses a subject line vs. a thesis thesis statement, Similar in some and itemization of points vs. body paragraphs, ways, different in Organization transitional words transitional words, others Uses topic sentences only and topic when needed, dependent sentences upon the type and length of correspondence Uses short, denotative words; Uses longer, short sentences; and short connotative words; Different Style paragraphs longer sentences; and longer paragraphs Uses highlighting techniques, such as graphics, headings, Not usually a Document subheadings, various fonts, factor Different Design white space, bullets, etc. The five components People read literature for pleasure, essays for listed above are enlightenment, and journalism for news. People discussed in greater detail on the read technical writing to accomplish a job. following pages. 6 Five Components of Writing Development If you have been teaching your students to develop their essays using such traditional means as examples, anecdotes, testimony, data, and research, then teaching technical writing will not be a strain. The same development techniques are applicable when the students write memos, letters, and reports. Grammar Grammar is important in essays. It might be more important in technical writing. Whereas errors often can hide in longer essays, those same errors loom large in one page memos or letters. In a survey (Gerson) of over 700 technical writers (coast to coast) asked to list important aspects of correspondence, 98% ranked correct gram- mar as an essential component of successful writing. Grammar is not merely the concern of English teachers. Professional writers and business people perceive it as essential. Organization Essays employ topic sentences, transition between and within paragraphs, and a thesis statement. Technical writing usually does not. In a memo, letter, or report, the thesis would be replaced by a subject line. The different aspects of organization help distinguish technical writing from essays. Since paragraphs are shorter in technical writing (often between one to three sentences) than in many essays, topic sentences are less important. Transitional words and phrases in an essay can be replaced by an enumerated list, by a list of bullets (%, etc.), and/or by headings and subheadings. Style Of greater importance is the different style (word usage, sentence structure, and paragraph length) used in essays versus technical writing. Essays rely on longer, more connotative words; longer, more complex syntax; longer, more detailed paragraphs. Technical writing, in contrast, demands short, denotative words; short, simple sentences; short (Continued on next page…) 7 Style (continued) paragraphs with information clarified through graphics (pie charts, line graphs, etc.). It has everything to do with audience and purpose. The reader of technical writing does not have time, nor necessarily an interest in the subject matter. Envision this scenario. It is the night before Christmas, your children are asleep, and you are trying to put together a Christmas present—a doll house, a train set, etc. To assemble this present, you are sitting on the floor (you have been sitting there for two hours, as your aching back attests). You are trying to read the complicated instructions which accompanied the toy (those instructions are a type of technical writing). You do not enjoy the activity. In fact, you just want to end the task and go to sleep. That is a typical technical writing situation. The same holds true when you read an instruction to install software, build a cabinet, lay tile, or any other task. People do not read technical writing, such as instructions, for pleasure. The writing is a means to an end. Thus, to help people accomplish the task as quickly and as efficiently as possible, the writing style should be concise—short words, short sentences, and short paragraphs. Document Design Document design refers to the physical layout of the correspondence. Essays consist of words, words, and more words, separated by indentations to create paragraphs. Technical writing, in contrast, uses highlighting techniques and graphics for visual appeal to help the reader access and understand the data. Technical writing is written to a different audience for a different purpose than essays. The reader of technical writing does not have time, nor necessarily the interest in the subject matter. 8 Conclusion: If we want students to write technical documents, we need to define what technical writing is and provide a context for writing such documentation. This first chapter may be used to accomplish those goals. End-of-Chapter Activities Read, Lecture, Invite, and Test Read this chapter for your own knowledge. Use this information to acquire a better understanding of technical writing or as a reminder of what you’ve always known. Lecture from the chapter. Teach from this information to clarify for your students why technical writing is important, what technical writing entails, and how it differs from the type of writing they are used to. Invite people from business and industry to your classroom to discuss how technical writing is important to them. Test students on the information in this chapter. A short test could include the following: What percentage of time does a manager spend writing? Or a new employee, or a CEO? How does technical writing differ from essays? List at least three ways. Define technical writing. List five types of technical writing. Explain the writing continuum, giving examples to prove your points. Have students create their own definition of technical writing Students could gather examples of technical writing (such as memos, letters, reports, brochures, or instructions), or you could bring in examples (this Teachers’ Guide provides you several examples). The students can get examples from their parents, from businesses, or in your school’s office. Once they have examples, break the students into groups and have them review the examples. Ask them to brainstorm the examples’ unique characteristics (page layout, length, tone, content, word usage). Next, give them essays—or poetry, or drama, or a short story, or a newspaper. Ask them to compare the technical writing to the other types of correspondence. Based on these discussions, ask the students to create their own list of technical writing criteria. Finally, ask the students to create a technical writing rubric, perhaps comparing it to Six Traits. Write and Rewrite Have the students write a poem (or an expressive essay or an expository essay) about a classroom object (a stapler, an eraser, etc.). Then have the students take the same subject and write a technical memo, complaint letter, recommendation report, instructions for using the object, or a manufacturing specification. Compare and contrast the results. 9 Chapter Two In this Five Traits of Chapter... Technical Writing Students are not familiar with technical writing. Unless we teach them what this different type of communication en- 1. Clarity tails, they will continue to write essays (the writing skill they have practiced since grade school). This chapter provides specific criteria to give students before asking them to write techni- cal documents. The five traits of technical writing are: clarity conciseness accessible document design audience recognition accuracy Clarity in technical writing is mandatory The most important criteria for effective technical writing is clarity. If the audience responds to a memo, letter, report, or manual with, “Huh?” If a student fails to what has the writer accomplished? If the correspondence is not clearly clearly understand a understood, the reader will either call the writer for further clarification, or just ignore the information. In either case, the writer’s time is wasted; poem, a short story, the reader’s time is wasted; the message is lost. a play, or a novel, that is unfortunate; Clarity, however, is not just a time concern. Think of it from this perspective: your company has written an installation manual for a however, product. The manual, unfortunately, is not clear. When the reader fails equipment is not to understand the content, three negatives can occur: BAD—The equipment is damaged. This requires the owner to ship the damaged, no one equipment back. The company will replace the equipment, costs is physically accrue, and public relations have been frayed. hurt, and no one WORSE—The owner is hurt, leading to pain, anxiety, doctor’s bills, and bad public relations. is sued. EVEN WORSE—The company is sued. The company loses money, the writer of the manual loses a job, and public relations are severed. 10 Clarity achieved through reporter’s questions Ask your students: What don’t you know in This flawed memo, written by a manager to a newly hired employee, this memo? highlights the importance of clarity. What additional information should the Nothing is Date: March 5, 2004 writer have included for clear in this To: Michelle Fields clarity? From: Earl Eddings memo, and Subject: Meeting Obvious responses: the reasons are When’s the meeting? obvious. The Please plan to prepare a Where’s the meeting? manager has Who’s the meeting for? presentation on sales. failed to How much information is “very detailed”? answer Make sure the information How will the presentation Reporter’s is very detailed. be made? Questions: Why is this meeting being Thanks. held? who, what, What does the manager when, where, want to be conveyed why, how. about sales? Reporter’s Questions Checklist Who is the audience? Who will know what? Will the audience know a great deal (High Tech)? Will the audience know a little about the topic (Low Tech)? Will the audience know nothing about the topic (Lay)? do you plan to do? What do you want the audience to What do? What do you want to know? should the job be completed? What’s the turnaround When time? What’s the timetable? What’s the desired schedule? When do you need an answer? Where will the work take place? Why is the task being undertaken (the rationale, motivation, goal)? Why is the desired date important? How should the task be performed? What’s the preferred procedure? 11 Date: March 5, 2004 To: Michelle Fields From: Earl Eddings Subject: Sales Staff Meeting Using the Reporter’s Questions Checklist as a prewriting tool, Please make a presentation on improved sales the previous memo techniques for our sales staff. This meeting is could be revised to planned for March 18, 2004, in Conference Room C, from 8:00 a.m. - 5:00 p.m. achieve greater clarity. Here is an Our quarterly sales are down 27%. Thus, we example of a revised need to help our staff accomplish the following: 1. Make new contacts. memo. 2. Close deals more effectively. 3. Earn a 40% profit margin on all sales. Use our new multimedia presentation system to make your presentation. With your help, I know our company can get back on track. Thanks. Clarity achieved through specificity When a student answers reporter’s questions, he or she has filled a page In contrast to with words. But all words are not equal. Words like some, several, mystery stories many, few, frequently, often, substantial, or recently will take up space on the page and convey an impression. These connotative words will which seek to create not mean the same thing to everyone. suspense, technical If a memo sent to six employees states that the company has lost a writing must be substantial amount of business, will all employees acquire the same clear. knowledge? One might assume that a substantial loss equals 1,000; another might assume that a substantial loss equals twelve clients. In each case, the employees are guessing, and that is not the goal of The ultimate goal of successful technical writing. effective technical writing is to say the (The previous memo using the phrase very detailed would be more clear if the writer had said he needed an eight hour presentation. Everyone same thing to receiving the memo then would know exactly how much time they multiple readers needed to set aside to attend the meeting.) 12 Read the following paragraph, taken from an actual business correspondence: 2. Conciseness “In order to facilitate an efficient meeting and fuel thought processes prior to June 25, I want to provide you with a brief overview of discussions recently carried out at the director and manager level within the process. These discussions involved personnel from Accounts Payable, Information Services, Procurement/ Materials Management, Financial Systems, and Property Accounting, centering on a proposed framework for managing process improvement moving forward.” Do you understand this letter? Do you remember what you read? Did you even finish reading it? Successful technical writing should help the reader understand the text, not present challenges to understanding The above paragraph is not successful writing. It fails to communicate clearly because it is too long-winded. In this case, conciseness actually No one curls would aid clarity. up in bed at Isn’t it the responsibility of the reader to figure it out? No. The responsi- bility is with the writer. Here is why. night and for If an individual reads literature, it is his or her responsibility to under- pleasure reads stand the writing. Creative writers seek to challenge us. However, manuals about technical writing, as noted in Chapter 1, is not literature. We read technical writing because it is a job requirement. installing Good technical writing is concise. It is a tool for the readers to use to computer accomplish whatever job they are doing. In contrast to traditional essays, effective technical writing uses short words and short sentences. printers. 13 Conciseness has unique importance in technical writing Where’s the user manual for your car? It’s inside the glove compartment. In other words, that piece of very complex technical writing had to be written concisely enough to fit inside a specific-sized box. The content took a backseat, so to speak, to the user manual’s predetermined location Technical within the car. Writing Here’s another example: what’s the perfect length of a Must resumé? One page, of course Guess what? That’s a box. We have decided that a great resumé should fit inside a Fit in typical, 8” X 11” piece of paper. the Box Now, think about the size of an e-mail screen. Yes, the “box” is shrinking. A typical e-mail screen measures about 3” X 6”. A Palm Pilot monitor is about 2” X 2”. Your cell phone monitor is about 1” X 1”, and a pager’s monitor is closer to ¼” X 1½”. In each instance, the writer has less and less room to write. Successful technical writing tries to avoid multisyllabic “mul-ti-syl-lab-ic.” words such as Conciseness achieved through short words Teach students to use one and two syllable words. Of course, some multisyllabic words can not be changed. We can not replace engineer, telecommunications, or Internet. Other words, however, can be avoided. Look at these, for example. Changing Long Words to Short Words Long Words Short Words cognizant know endeavor try domicile home morbidity death terminate end 14 Conciseness achieved through short sentences Here is an unsuccessful example of technical writing: You can shorten “In order to successfully accomplish their job a sentence by functions, the team has been needing more work avoiding: space for some time now.” redundancy An improved sentence would read, prepositional “The team needs more work space to do its jobs.” phrases The first sentence contains 20 words and 28 syllables; the second sen- passive voice tence contains ten words and ten syllables. Avoiding redundancy Why say, “The used car will cost the sum of 1,000.00”? It is more concise to say, “The used car will cost 1,000.00.” In this instance, “the sum of” is redundant. The following examples replace redun- dancy with concise revisions: Less Wordy Sentence Wordy Sentence We collaborated to- We collaborated on gether on the projects. the project. This is a brand new This is an innovation. innovation. The other alternative is The alternative is to to eat soup. eat soup. Avoiding prepositional phrases Prepositional phrases create wordy sentences. Consider the following examples (note that the prepositional phrase is in bold type): Concise Sentence Wordy Sentence He drove at a rapid He drove rapidly. rate. I will see you in the I will see you soon. near future. I am in receipt of your I received your e-mail e-mail message re- message requesting a questing an increase pay raise. in pay. 15 Avoiding passive voice Passive voice constructions are weak for at least two reasons. They are wordy, and they replace strong verbs with weak verbs. Example: “The window was broken by the boys.” versus “The boys broke the window.” The first sentence contains seven words and the weak verb was. In contrast, the second sentence contains five words and the strong verb broke. The emphasis is placed on the individuals (boys) rather than on an inanimate object (window). Other examples follow: Passive Voice Active Voice It is my decision to run I decided to run for for office. office. There are sixteen Sixteen people tried out people who tried out for the basketball team. for the basketball team. The computer was Tom purchased the purchased by Tom. computer. In addition to clarity and conciseness, a third trait of effec- 3. Accessible Document tive technical writing is accessibility (page layout— Design the way the text looks on the page). Look at the following paragraph: Regarding part number 315564-000, we received 541 units of wafer 3206-2. These were rejected. For the same part number, we received 643 units of wafer 3206-4. These were accepted. Three hundred and twenty- nine units of wafer 3206-5 from the same part number. These were accepted. Next, 344 of part number 315564-000’s wafer 3206-6 were accepted. However, the 143 units of wafer 3206-7 (same part number) were rejected. Finally, all 906 units of wafer 3206-8 were rejected. These also were from part number 315564-00. 16 Wall-to-wall words turn off readers. Highlighting techniques make the text open, airy, and inviting Students can make information leap off the page by making content accessible through the following highlighting techniques: Graphics (table and figures) The paragraph on the bottom of page 16 consists of 84 words and ten White space sentences. The average number of words per sentence is only 8.4. Because the sentences are not too long, the writing is concise. Next, Boldface text the text is clear, due to specificity of detail. However, despite the Headings and clarity and conciseness, this writing fails. Why? Essentially, this subheadings paragraph is unintelligible. The page layout makes it nearly impos- sible for the reader to understand the text. Italics Using highlighting techniques (tables, headings and subheadings, Underlining different font sizes, column lines, and white space), below is a revised Varied Font sizes copy of the information presented on page 16. Bullets (&'()) Part Number 315564-00 Numbered lists Quantity Varied Font types Wafer Accepted Rejected Received (computers offer many options) 3206-2 541 X 3206-4 643 a" 3206-5 329 a" 3206-6 344 a" 3206-7 143 X 3206-8 906 X 17 4. Audience Recognition Who is writing to whom? What does the audience know, need to know, and want to know? When your audience fails to understand the text, you have failed to communicate Recognizing your audiences Successful technical writers know that they can only achieve clarity by recognizing their audiences. Basically, our students will write to either Writing High Tech Peers, Low Tech Peers, or Lay Readers. These three audi- ence levels have the following traits. successfully to High Tech Peers know as much about a subject matter as you. They these three have the same job title, same education, same years of experience, and types of the same level of expertise. For example, a medical doctor writing to another medical doctor would be writing High Tech to High Tech. audiences Low Tech Peers who work in your company know something about requires the subject matter. They may not have the same job title, education, years of experience, or level of expertise. For example, a medical different doctor writing to a staff nurse would be writing High Tech to Low Tech. techniques. Lay Readers are your customers. They are completely out of the loop. For example, a medical doctor communicating with a patient. High Tech Peers High Tech and High Tech and Low Communicating Lay Reader Tech Peer 18