

The Manual of Technical Communication: A Practical Guide to Writing Documents

SmashWords Edition

Copyright © 2014 by UAH Business and Technical Writing Program

Published by the UAH Business and Technical Writing Program

301 Sparkman Drive

Engineering Building, Room 117

Huntsville, AL 35899

ISBN 978-1-4951-2013-8

**Smashwords Edition, License Notes**

This ebook is licensed for your personal enjoyment only. This ebook may not be re-sold or given away to other people. If you would like to share this book with another person, please purchase an additional copy for each recipient. If you're reading this book and did not purchase it, or it was not purchased for your use only, then please return to Smashwords.com and purchase your own copy. Thank you for respecting the hard work of this author.

This work is made available under the terms of the

Attribution-NonCommercial-NoDerivs 3.0 Unported

Creative Commons license.

The text may be reproduced for non-commercial purposes,

provided that credit is given to the original authors.

To view a copy of this license, visit

<http://creativecommons.org/licenses/by-nc-nd/3.0/>

Please contact Dr. Ryan Weber of University of Alabama in Huntsville

at rw0019@uah.edu for permission beyond the usage outlined in the Creative Commons license.

For more information about the UAH Business and Technical Writing program,

visit the UAH English Department Website.

_ Acknowledgements _

The following work is the result of the collaborative effort of Dr. Ryan Weber's Fall 2012 Theory and Practice of Technical Communication class and Dr. Cynthia McPherson's Spring 2013 Problems in Technical Editing class at the University of Alabama in Huntsville. Students have put forth their best efforts to clarify and explain some of the more common documents encountered by technical communicators.

These writers are

Jay Cavender

NiCarla Friend

Danielle Hart

Nicholas Mezmar

Cody Roy

Kristyna Selph

Tamara Smith

Ruby Stevens

Lucas Stewart

Evan Taylor

Bonnie Winstel

and Dr. Ryan Weber

The editors are

Alan Chong

Jennifer Fields

NiCarla Friend

Erin Gowdy

Michelle Massey

Dane Parker

Kristyna Selph

Evan Taylor

## The Manual of Technical Communication

### Table of Contents

Introduction

Chapter 1: Overview of Technical Communication

Chapter 2: Proposals

Chapter 3: White Papers

Chapter 4: News Releases

Chapter 5: Software Documentation

Chapter 6: Procedures

Chapter 7: User Manual

Chapter 8: Drug Package Inserts

Chapter 9: Flyers

Chapter 10: Resumes and Cover Letters

Chapter 11: Memos

References

Introduction

This book introduces technical communication and several types of technical documents. Technical communication explains complex technologies or complex concepts to readers so that they can comprehend and use the information. Good technical communication is clear, concise, user-centered, and useful. Technical communication exists to be used, so it should help readers get things done. As technical writing scholar David Dobrin argues, technical communicators "should put [information] in only if the reader can use it" (121).

In some ways, this book itself serves as a kind of technical communication in that it presents complex material to potential users. If nothing else, it explains several types of documents—proposals, white papers, news releases, software documentation, procedures, user manuals, drug inserts, flyers, resumes, cover letters, and memos—to the user. It primarily does so through structure. Each chapter about a technical document, for example, is organized into four sections:

  * **What?** What is this document? What is its nature? What type(s) of workplace contexts might prompt a technical communicator to compose it?

  * **Why?** Why do people write this document? What specific purpose(s) does it serve? Why is it important?

  * **Who?** Who reads this document? Who is the target audience? Who might be interested in the information it conveys?

  * **How?** How does one write this document? What is the methodology behind its composition? What are its components? What is the layout? What might it look like?

This structure does more than simply lend the chapters much needed organization. It also makes blocks of text seem more manageable to the user, just as breaking a novel into chapters makes a dense book seem less daunting. Compartmentalizing text, particularly with headings, also improves usability. Should users not wish to read an entire chapter, the labeling of the smaller units of text allows them to locate the desired section much more efficiently. If readers want more info on a given topic, they can follow the hyperlinks at the end of each chapter for document examples and additional writing advice.

Eleven technical communication students composed this book in the span of the 2012 fall semester at the University of Alabama in Huntsville (UAH). Based on experience levels and skill sets, each student wrote a section or chapter. Eight students edited the book during the 2013 spring semester at UAH. For more information about the book or technical communication at UAH, please contact Dr. Ryan Weber at rw0019@uah.edu.

Chapter 1: Overview of Technical Communication

This chapter provides an overview at technical communication and offers insight into how writers produce effective technical communication.

What Is Technical Communication?

Some might define technical communication as communicating about technology, whereas others might argue that it is communicating in a technical style. Although it may be characterized by subject matter and style, technical communication cannot be summed up by its components, as it is too vast a field. Simply put, technical communicators translate complex information into more readable material for a specific audience. Concise, clearly-expressed sentences come into play here, as do structural elements, such as headings, bulleted lists, white space, and illustrations. Technical communicators employ these tools to make information more accessible for the intended audience.

In order to accomplish this task, today's technical communicator does far more than merely write print documents. In addition to traditional print materials, such as grants, proposals, procedures, memos, cover letters, white papers, and instruction manuals, today's technical communicators have many other media at their disposal. The digital era has given technical communicators the luxury of video, podcasts, wikis, blogs, online documentation, and various other multimedia platforms.

Regardless of the ever-growing number of complex tasks, a technical communicator's primary purpose is still accommodating information for users. At the most basic level, technical communicators function as translators of sorts, mediating, for instance, between engineers, programmers, and technology users. Engineering jargon and highly technical concepts must be made accessible to users. Otherwise, even the most groundbreaking development will fail to reach an audience.

Imagine a world without technical communicators. Even the most user-friendly products, like plasma TVs and iPads, would be difficult to operate without some form of user help. Users would have difficulty troubleshooting even the most routine Mac or PC problems without support documentation. Manipulating the ever-changing interfaces of Facebook and iTunes would be daunting without the luxury of online documentation. Anyone who has tried to update their Facebook privacy settings knows the importance of clear, easily-accessible instructions (such instructions are even produced by Facebook users themselves). More complex technologies and machinery require very sophisticated technical communication to operate successfully, and missing or ambiguous information can prove disastrous; for instance, a government report found ambiguous instructions partially to blame for the 2010 BP Deepwater Horizon oil spill. A society so utterly dependent on technology must be able to make sense of it. Technical communication makes that possible.

Why Is Technical Communication Important?

Writing and communication skills matter to workplace success. Forbes magazine ranked "Top Notch Communication Skills" as the first of the seven most universal job skills. A landmark report conducted by The National Commission on Writing for America's Families, Schools, and Colleges concludes that in today's workplace, writing is a 'threshold skill' for hiring and promotion among salaried (i.e., professional) employees" ("Writing"). In other words, unless applicants have great facility with language, they will not fare well in the job market. Just as employers expect basic typing and computer competency, strong communication skills are a requirement for professional success.

Although the demand for highly effective communication is hardly exclusive to technical fields, the relative scarcity of this skill in these professions is somewhat alarming. Take a look at engineers, for instance, who can spend up to 40% of their work time communicating via written works, oral exchanges, and presentations. The problem, according to the _Journal of Engineering Education_ , is that "although today's fast-paced, competitive workplace requires engineers to convey technical information quickly to diverse audiences, the overwhelming evidence shows that graduating engineers are inadequately equipped to meet this need" (Sageev and Romanowski 685). A 2011 report from the United Kingdom's Department for Business Innovation and Skills found that employers ranked STEM (Science, Technology, Engineering, and Math) graduates poorly on their communication skills. While many engineers are excellent writers, many more are poorly educated to perform one their major job duties. Some universities and colleges, in an effort to address this deficiency, now require engineering students to take technical communication courses. While this solution may help future engineering graduates cope better in the workplace, it does little for the thousands of under-prepared professional engineers already out in the world. In this case, they turn to technical communicators.

Who Writes Technical Documents?

Most professionals write technical documents, even if their job title does not specify them as writers. Corporations need documents to get things done, and the writing responsibilities fall to almost everyone in the organization. Many new professionals are surprised by how much writing they do in their day-to-day jobs. However, some companies also hire technical writers and communicators to specifically handle many of the writing and editing responsibilities. These writers work with Subject Matter Experts (SMEs) to produce documents for users of company products.

This section discusses collaborative writing, document review processes, audience analysis, and researching information.

Collaborative writing

Complex document creation usually begins with an individual but can transform into a team effort. A typical writing project may require input from several specialists:

  * Subject Matter Experts (SMEs), engineers, or programmers will produce a technical product and some of the documentation.

  * Technical communicators will deliver varied types of documents based on standard procedures inside the organization.

  * Editors perform several levels of editing, making sure that the document is clear, comprehensive, and correct.

  * Management and Quality Control assure that the results are cohesive and maintain the standards of the organization. Some documents may undergo legal review as well.

  * Designers format the information for reading on a page, website, or mobile device.

Often, technical communicators may perform several of these tasks, and well-rounded technical communicators have expertise in writing, editing, and design. In fact, the writer who only produces manuals is becoming a rarity (Catanio and Catanio). Technical communicators can actively participate in meetings and elaborate their concept of the product to others. They can recognize problems through the review process that accompanies the creation of documents. Technical communicators can be important to a team's developmental progress.

Working on a team requires a refined knowledge of the project objectives. The information generated by an engineer or SME may be geared toward an expert audience; technical communicators work with the SME to adapt this information for a larger audience. Often, technical communicators conduct several interviews with the SME to get all the necessary information for a project. Solid teams employ writers who ask pertinent questions and get good answers. The interviewee may have the information, but getting it can be a challenge due to varying perspectives and personality types of team members. Writers should be professionals and communicate well with others (Lee and Mehlenbacher). Technical communicators also benefit from a strong understanding of the knowledge, vocabulary, and technology unique to their industry.

Document Cycling and Review Processes

Writers should know how documents move, or cycle, through their organization prior to publication. The document cycling and review process can vary with the type and size of teams and organizational hierarchies. The document cycling process depends on teamwork, clarity in communication, and various levels of approval. Writers and SMEs tend to work in close proximity and information flow must be fluid. Typically a supervisor will review the writer's product and recommend changes, then review subsequent drafts. Upon approval, the document will move to a management office for further approval, which could involve quality control and legal teams. Corporate approval is an important step in production. The redundant review system of "gatekeepers" ensures that documents project a consistent corporate voice. According to DeKay (2007), this hierarchy helps establish a universal tone for published documents. The quality assurance and approval process creates formal publications that meet the standards of the organization.

Modern review processes can incorporate programs such as Microsoft Sharepoint. The software allows technical writers to upload drafts so that any relevant team member can access and modify content. Experts and managers will review the items, make annotations, and save the results. System alerts let the team know when changes have been made. Once the revisions are complete, the deliverable is then ready for production. A librarian will place the files in a repository available for future reference. Government systems may have additional verification tests for the documentation (Arrowood, 2012). In addition to Sharepoint, many writers benefit from Google Docs, which allows multiple contributors to access an online document, edit it, and save changes that are visible to everyone in the team.

Identifying the Audience

Technical communication intends to communicate ideas or provide directions to an audience. The primary audience of any document are the readers who need to use the information. People rarely read technical documents for fun, so write for the audience who will do something with the document. The primary audience for a document is rarely "everyone in the world" or "an average reader" - instead, audiences are made up of identifiable groups, such as "mechanics servicing 787 aircraft" or "professional employees using Excel."

Sometime writers may get so preoccupied with creating the document that they forget the readers' needs. Such forgetfulness is unfortunate because audience affects all aspects of the technical document. Writers should consider certain aspects of the audience such as

  * Who is the audience? What factors, such as audience age, gender, educational level, vocabulary, economic status, ethnicity, culture, nationality and beliefs must be addressed?

  * What will the audience do with the document and how will they use it? Will the document simply provide information or will it be used to perform a task? In what context will the audience use the document?

  * How will the audience access the document? Will they view it on paper, a computer, or a mobile device? Could any technology restrictions or disabilities interfere with audience members accessing the information?

  * What level of understanding does the audience have about the subject matter? Are they novices, intermediate, or specialist readers?

  * Does the audience have biases, prejudices, or preconceived notions about the subject matter? Does the audience already have a negative opinion of the product? Is the audience hesitant or anxious about learning new technology? Does the subject matter go against the values of the audience?

The more effectively writers anticipate audience needs, the more effectively they can craft communication that meets those needs. Writers can use well-developed questionnaires and focus group questions to get insight into the intended audience. The writer can also use social media, product reviews, help desks, and sales departments to get insight on audience needs and concerns. These resources can alert the writer to the level of understanding the audience has, the vocabulary the audience uses, demographic information about the audience, and potential biases audience members might hold about the subject matter.

Determining Purpose

All pieces of writing have a purpose. Writing consultant Matt Copeland says that "Focusing on purpose as one writes helps a person to know what form of writing to choose, how to focus and organize the writing, what kinds of evidence to cite, how formal or informal the writing style should be and how much should be written." However, John S. Harris, founding president of the Association of Teachers of Technical Writing, believes it is equally important to consider two types of writing purposes: the readers' and the writers.'

The writer and reader may have different purposes and needs. Writers may hope to inform, persuade, or help readers. The writer's purpose is more often than not predetermined by other people within the organization. However, the organization's goals may differ from the readers.

Ultimately, the writer must prioritize the needs of the reader who plans to use the document. Readers usually read technical communication because they want to complete a task or solve a problem, and they often turn to a document only after exhausting other options. In the article "The Project Worksheet for Efficient Writing Management," John S. Harris outlines four questions he believes writers should consider regarding the readers' purpose and needs (38).

  * **What should the reader know after reading?** Highlight this information using tables, charts, lists, and outlines.

  * **What should the reader be able to do after reading?** This may be different from what the reader knows and may depend on the technical skills of the reader.

  * **What attitude should the reader have after reading?** Just as the writer will have an attitude before reading, the writer must decide what attitude the reader should have after reading the document. The writer should want "the reader to think that the document was prepared by a credible and meticulous professional who cares about the subject, the needs of the reader, and the needs of his or her employer" (39).

  * **How will the reader access the information?** Technical documents are rarely, if ever, read from start to finish. Therefore, a well-designed text will help readers find important information quickly. "The more important the information, the more accessible it should be" (40).

Locating and Researching Information

Technical communicators conduct both primary and secondary research for the many documents they produce. Often, they spend as much time locating information as they do writing the document (Zeleznik 79). While certain aspects of technical research are similar to academic research, the following types of research are more suited to business organizations.

  * **Hands-On Experience:** Previous experience regarding the subject matter or a similar document can jog the memory and provide valuable information. Additionally, technical writers can often use the software or product before they write about it.

  * **Interviews:** Interviewing skills are valuable for technical communicators and one of the most effective ways to obtain information. They are effective because they allow the writer to get information directly from the source. Subject matter experts, clients, customers, and co-workers (such as help-desk representatives) can provide the writer with valuable information. The best interviews go through three stages: preparation, interview, and follow up.

  * **Request and Response Letters:** Letters and email messages often provide the same access to information as interviews. Many technical communicators prefer this format over interviews because it saves time and money by eliminating face-to-face meetings and allows them to reach more individuals.

  * **Surveys:** Surveys allow the writer to glean information from large groups at a low cost. Questions can gather information about audience needs, expectations, or concerns. Several free and low-cost electronic survey tools allow researchers to disseminate surveys online.

  * **Internal Resources:** The resources your organization has on hand—such as personnel, financial services and product information — are valuable sources of information.

The sources will not only provide information you need to complete the document, but they may also provide information about the audience and purpose if used at the beginning of the writing process.

How Do Writers Develop a Technical Communication Style?

People often wonder what makes writing in technical communication different from "regular" writing. But this question assumes that there is such a thing as "regular" writing. Every writing context requires a different style. Writing style is not universal because there are so many social and professional contexts in which writing occurs. Everyone knows that writing a shopping list or a note to a friend is different from writing an academic paper. Even in academia, writing style varies between disciplines; a paper on Renaissance poetry, for example, requires a different style from a chemistry lab report.

But where exactly does technical writing fall in the spectrum of writing? What stylistic features, in other words, characterize writing in technical communication? Since the main purpose of technical communication is to make technology understandable to users, every aspect of the writing should be clear and direct (Alred, Brusaw, and Oliu 544), and word choice and sentence structure should not confuse readers or make the meaning unclear. Most organizations and companies (such as IBM) have style guides which outline the preferred corporate style. If a style guide is not available, observe the general principles described in this section of the book:

  * use the active voice over the passive voice

  * choose effective words

  * use sentence structures that reflect the ideas you want to convey

Use Active Voice Rather Than Passive Voice

Voice is a grammatical term that describes verbs. Specifically, voice tells the reader whether the subject of the sentence performs the action of the sentence or is acted upon by another agent (the agent may or may not be explicitly stated in the sentence). Consider the two sentences below:

Active: The boy broke the vase.

Passive: The vase was broken by the boy.

In both of these sentences, the boy performs the action, but the passive voice example places the grammatical emphasis on the thing that is acted upon, the vase. In technical communication, writers often use the active voice because it takes less mental processing on the part of the reader and often makes sentences shorter and clearer. It works better to say "The manager called a meeting to discuss what staff should do to increase productivity" than "A meeting was called by the manager to discuss what measures should be undertaken by staff to increase productivity." Active voice makes sentences simpler and clearer.

The active voice works especially well in instructions and use manuals. Compare these two sentences:

Unclear: The screw should be installed using a flathead screwdriver.

Clearer: Install the screw with a flathead screwdriver.

The second sentence places the emphasis on readers and the actions they should perform, making it clearer to the readers.

Many English teachers tell their students to never use passive voice, and avoiding passive voice often makes sense. However, some situations benefit from the passive voice. The passive voice should be used in some genres of writing, such as science and engineering writing. For instance, a survey found that NASA employees prefer the passive voice (Pinelli, Barclay, Kennedy, 1997). Science writers often use passive voice because the agent (the performer of the action) matters less than the action itself. Writers also use of passive voice when the agent is unknown. Journalists often use the passive for this reason, especially in crime reports. "The victim was murdered" or "The bank was robbed" are used if the criminal is unknown. Politicians often use passive voice to avoid admitting blame. They say that "mistakes were made" rather than "We made mistakes."

In general, use active voice unless you have a good reason to use passive voice.

Choose the Right Words

Word choice also affects reader comprehension. Since technical writing should express ideas clearly, avoid using big words when simple words will do. The overuse of complicated words can frustrate readers: "fancy" language draws attention to itself, rather than to the ideas the writer is trying to convey. As technical communication experts Sam Dragga and Elizabeth Tabeaux argue, "Write to express, not to impress." Use jargon only if the audience will easily understand that jargon. In other words, use technical language when necessary if writing to technical audiences, but avoid technical language if writing to non-technical audiences. If you absolutely must use a technical term when writing for a non-technical audience, explain it clearly.

Consider the relative clarity of these two sentences:

Unclear: The efficaciousness of innovative legislation regarding the confidentiality of consumer information on the websites of internet-based retailers is undeniable when considered as a means to aid in the reduction of identity theft.

Clearer: New laws about customer privacy on retail websites will help reduce identity theft.

The second sentence is clearer for a number of reasons, but one of the most important reasons is word choice. The second sentence uses simpler words, such as _new_ instead of _innovative_ , and the writer removes unnecessary words ( _efficaciousness_ , for instance). The writer also clarifies the writing by engaging in good word choice techniques: avoiding nominalizations, using strong verbs, and editing redundant phrases.

Avoid Nominalizations

A nominalization is "a verb turned into a noun" (Rude and Eaton 234). Nominalizations can be identified by suffixes like _-tion, -ment, -al, -ence, -ance, and -ing_ (Rude and Eaton 234). _Development, production, fulfillment,_ and other words like them are verbs in hiding: the active verbs _develop, produce,_ and _fulfill_ are inherent in the meaning of the nominalizations. In the first sentence of the previous example, _reduction_ is a nominalization. In the second sentence, the writer replaces the nominalization with _reduce_ , which more clearly shows the action of the sentence. Consider the two sentences below:

Unclear: Implementation of the new policy will occur on Monday.

Clearer: Managers will implement the new policy on Monday.

Turning the nominalization into the main verb makes the action of the sentence clearer.

Strong verbs often "hide in nominalizations" (Rude and Eaton 233). If the sentence contains a nominalization combined with a weak verb, consider changing the nominalization into the main verb and removing the weak verb entirely (Rude and Eaton 233). Use _meet_ instead of _hold a meeting_ , _decide_ instead of _make a decision_.

Use Strong Verbs

Writers often use weak verbs when strong verbs would have greater impact. Overuse of the _be_ verb and other weak verbs such as _have, make, involve, deal with, give,_ and _use_ leads to longer, less clear sentences (Rude and Eaton 233). Strong verbs, on the other hand, simplify and clarify sentence meaning. Consider these two sentences:

Weak Verbs: The experiment will deal with the effect that screen images in documentation have on user experience.

Strong Verbs: The experiment will examine how screen images in documentation affect user experience.

The verb _examine_ more accurately expresses what the experiment will do than _deal with_ ; likewise, the verb _affect_ replaces the weak verb _have_ in the phrase _the effect that screen images have._

Edit Redundant Phrases

Phrases that say the same thing twice or that say more than necessary to convey the idea make writing redundant and clumsy. Shorten phrases that are longer than necessary. For example, think about this lengthy phrase from earlier in the chapter: _a means to aid in the reduction of identity theft_. The same idea can be conveyed with the simple verb phrase _help reduce_ or even merely _reduce_. Any phrase that weakens the impact of the verb or noun it contains can probably be edited to improve the flow of the writing.

Joseph M. Williams writes in _Style: Toward Clarity and Grace_ , "Every word implies another," so only add extra words if the meaning of the second word is not implicit in the first (116). There is no need to write the same thing twice, so phrases like _uniquely one-of-a-kind_ are redundant. Something that is unique is one-of-a-kind, and vice versa, so choose one.

Another type of redundancy can occur when verbs are paired with prepositions that are implicit in the verbs themselves. It is not necessary to say _return back_ or _return again_ because the prepositions are inherent in the _re-_ prefix of the verb (Williams 117).

A final type of redundancy occurs when the category of a word is expressed in addition to the word itself. Readers know that blue is a color, so it is not necessary to write _blue in color_. Just write _blue_. Eliminating redundancy makes sentences clearer.

Use Sentence Structure Effectively

Always keep in mind that you are writing for maximum clarity. This point cannot be overemphasized. The principle of clarity does not mean that you have to write in short, choppy sentences, but it does mean that you should write sentences that readers can understand the first time through. Length does not necessarily indicate whether a sentence is well-written or badly-written; instead, a well-written sentence is well-written because the reader understands the ideas expressed in the sentence and the relationships between those ideas. Joseph M. Williams puts it like this: "Clear writing does not require Dick-and-Jane sentences. What counts is not the number of words in a sentence, but how easily we get from beginning to end while understanding everything in between" (25). Sentence structure should reinforce meaning (Rude and Eaton 221). Keep these two principles in mind: reflect the main idea of the sentence in the sentence structure, and use parallel structures to indicate parallel ideas.

Reflect the Main Idea of the Sentence in the Sentence Structure

The grammatical subject and verb of a sentence and the main idea of a sentence are not always the same, but they should be in most cases. Consider these two sentences:

Main Idea Not Reflected in the Structure: The progress of the industrial revolution led to the development of new inventions such as the steam engine.

Main Idea Better Reflected in the Structure: The industrial revolution produced the steam engine, along with other inventions.

In the first sentence, the grammatical subject and verb are "progress" and "led," but these words do not represent the main idea of the sentence. The second sentence emphasizes the relationship between the industrial revolution and the steam engine, which is the invention under discussion. Placing the key concepts in the grammatical core of the sentence guides readers to the most important idea (Rude and Eaton 222).

Use subordination to further indicate the important ideas of a sentence. Put more important ideas in the main clause of the sentence and less important ideas in subordinate clauses. Consider the following two sentences:

Emphasis on Student Complaints: Although online plagiarism-prevention services help teachers better detect plagiarism, students complain that such services violate their privacy.

Emphasis on Plagiarism Detection: Although students complain that online plagiarism-prevention services violate their privacy, such services help teachers better detect plagiarism.

Grammatically, both sentences are correct. The context of the sentences determines which version is appropriate. If the writer wants to emphasize the student's unhappiness, then the first sentence is better because it places the idea of the students' complaints in the main clause of the sentence and the benefits of the services in the subordinate clause. If, on the other hand, the writer wants to emphasize the effectiveness of the services, the second sentence is better because the benefits of the services appear in the main clause while the student complaints are subordinated. Write sentences so that the main clause contains the main idea (Alred, Brusaw, and Oliu 526).

Use Parallel Structures to Indicate Parallel Ideas

Parallelism is the grammatical matching of elements that serve the same function in the sentence. It can occur at the word, phrase, or clause level (Alred, Brusaw, and Oliu 389). Often, readers do not notice when a sentence is written with parallel structures because the parallelism eases the flow of the sentence. The problem exists when a writer fails to use parallel structures to coordinate parallel elements of the sentence. The second sentence of this paragraph, _It can occur at the word, phrase, or clause level_ , is parallel: _word, phrase,_ and _clause_ are all the same part of speech, so the flow of the sentence is uninterrupted. The sentence would not be parallel if it read _It can occur at the word level, with phrases, or when the clauses need to match_. The non-parallel version of the sentence is choppy and more difficult to read.

Problems with parallelism often occur with the use of gerunds ( _-ing_ versions of verbs being used as nouns) and infinitives (to verbs). The following two versions of the same sentence show two similar problems with parallelism:

Not Parallel: I like to shop, swimming, and to hang out with my friends.

Not Parallel: I like shopping, hanging out with my friends, and to swim.

Parallel: I like to shop, to swim, and to hang out with my friends.

Parallel: I like shopping, swimming, and hanging out with my friends.

In each of the first two sentences, one of the items in the series does not match the others. The sentence could be made parallel either by making all the verbs in the series gerunds or by making all the verbs in the series infinitives: _shopping, swimming, and hanging out with my friends_ or _to shop, to swim, and to hang out with my friends_.

One good strategy to indicate parallelism clearly is to repeat structural clues like articles, prepositions, and conjunctions (Alred, Brusaw, and Oliu 389). For example, "We agreed that everyone should help with the project and that we should begin by creating a list of tasks." The repetition of that shows that both clauses are direct objects of the verb: "We agreed that X and that Y." When you write, use parallelism to indicate that elements of the sentence reflect similar ideas.

All the style principles in this chapter will improve your technical communication skills. Good technical communication happens when writers use every linguistic tool at their disposal to communicate their ideas in a clear, effective way. Use the simplest words that convey the meaning you need. Write sentences so that the agent and the action are clear and so that the structure of the sentence reflects the main idea. No book can cover every possible scenario in terms of style, but aiming for maximum clarity using the tips in this section will improve your writing and enhance reader comprehension.

Use Illustrations

Communicating an idea effectively requires that an author provide a clear message to their audience. When it comes to hitting this target, illustrations are a critical—and often necessary—arrow in the technical communicator's quiver.

What Are Illustrations?

Illustrations refer to visuals used to complement text or some form of verbal communication (such as presentations or speeches). Technical communicators use several types of illustrations. Basic categories of illustrations include charts, graphs, photographs, and tables. Programs currently used to create or render illustrations include Microsoft PowerPoint, Microsoft Visio, Adobe products such as Photoshop, FrameMaker, and Illustrator, and open-source software such as GIMP and ArtWeaver.

Strong technical communicators will be familiar with these programs or at least be capable of learning them. Aspiring technical communicators should begin familiarizing themselves with the basic capabilities of illustration programs and take any opportunities to work with them firsthand. Wikipedia is usually an informative place to start. Amazon.com provides the basic information about products, and the user reviews posted on their product pages are a good way get a feel for the experience other people have had using them. Additionally, short video tutorials are often available online through YouTube or the software company's website. Those looking to get hands-on experience may enroll in a local workshop that offers tutorials on these programs; checking with your local Society for Technical Communication chapter would be a good place to start. Otherwise, check online to see if trials of the programs are available for download. Lastly, one may always purchase these programs, but this approach can be expensive and undesirable if the technical communicator does not know whether he or she needs or wants a given program.

Why Do Technical Communicators Use Illustrations?

As noted before, illustrations complement the text they accompany. The adage "a picture is worth a thousand words" is especially true in technical communication. For good or ill, our culture has become a mass consumer of visual information (note the visually-oriented, textually-minimalistic venues of Facebook, Twitter, YouTube, and Pinterest by which we now communicate so much of our information).

Illustrations help writers achieve at least four goals:

  * Pique the interest of the reader

  * Engage visual learners

  * Explain information

  * Reinforce information

Illustrations can help individuals process information by presenting that information visually. For example, a project manager can more quickly surmise the most expensive part of a project by looking at a pie chart than by reading through a paragraph of text or listening to someone explain the same information.

How Do I Use Illustrations?

The technical communicator's use of illustrations should always involve several considerations. Principally, the use of illustrations should tie to the purpose of a document, but the technical communicator will also answer questions like these:

  * **What kinds of illustrations serve the purpose of the document?** There are several types of illustrations. These include the basic categories mentioned in this section. Some illustrations are described in more detail below.

  * **How much detail do the illustrations need to contain?** Detail can mean the actual technical information that is being conveyed or the aesthetic properties of the illustration—either of which can vary from document to document and even from illustration to illustration.

  * **How much time will it take to work on the illustrations?** Since creating illustrations is not as straightforward as typing text, an important part of time management for the technical communicator lies in the ability to estimate how much time it will take to create illustrations.

  * **Do I have the tools to create or work on illustrations?** Technical communicators can use several software programs to create illustrations. Not all employers and workspaces have these programs available for use, and most are not free, so availability can be limited. Before starting on illustrations, technical communicators should know the software tools at their disposal. They should also make sure that image formats are compatible with software used to create documents, online help systems, or mobile apps.

  * **Are my illustrations accurate and clear?** Naturally, the principles of clear and accurate writing carry over to illustrations. In a way, clarity matters even more for visual content. Going back to our example of the project manager, if the slices of his pie chart were scaled inaccurately and misrepresented project costs, the illustration would cause tremendous confusion. The significance of accuracy and clarity increases when matters of health and safety are involved. This applies not only to obvious matters—such as when showing the proper way to handle a power saw or putting clear warnings on dangerous medication—but also to seemingly mundane instructions, like those for assembling a chair, which may collapse and injure its occupant if it is not assembled correctly.

Types of Illustrations

The basic categories of illustrations are charts, graphs, photographs, and tables. Each offers distinct advantages and disadvantages for conveying information.

Charts

Charts refer to illustrations that typically show some kind of relationship between the elements they depict. Predominant subtypes of charts include the flowchart, organizational chart, and pie chart. Flowcharts often depict the chain of procedures, processes, or decisions of a collective body (like a company or company division) or individual position (like a director of human resources). Figure 1.1 is a partial (and facetious) example of a flowchart that applies to someone wanting to watch a movie on their computer.

Figure 1.1: Flowchart

Organizational charts depict the hierarchy of an organization or division. These communicate such information as the title and person holding a certain position, to whom they report, and whom they supervise. Figure 1.2 is an example of an organizational chart.

Figure 1.2: Org Chart

Pie charts break down information into percentages. They do not show a relationship between elements in quite the same way as a flowchart or organizational chart, but they effectively convey how parts of a whole relate to one another. Figure 1.3 is an example of a pie chart.

Figure 1.3: Pie Chart

Graphs

Graphs often depict data points based on two dimensions of measurement—one of which corresponds to a data point's vertical position, while the other corresponds to a data point's horizontal position. In practice, graphs are used to show how number or frequency changes across time. For example, media outlets occasionally use graphs to show how the nation's GDP has changed over the span of several months, as the graph in Figure 1.4 demonstrates.

Figure 1.4: Bar Graph

People also use several subtypes of graphs. Subtypes include the bar graph (a solid bar represents each data point), line graph (subsequent data points are connected by a line), scatter graph (data points are represented by stand-alone dots), and segmented graph (specialized bar graph). Not all subtypes work equally well for representing specific types of information and relationships. Make sure to choose the graph type that best represents the data you wish to convey.

Images

When used effectively, photographs and artwork can contribute to the design or efficacy of a document. Images are generally used in marketing materials to make documents more inviting to readers, but they can also be used in more technical documents to provide readers with a better understanding of a product or process.

Keep these tips in mind when using images in a document:

  * Ensure that the organization or publisher has ownership or publication permission for all images.

  * Images can appear very differently on a printed page than they do on a computer screen. If the photographs or artwork are going to appear on paper, make sure they are properly formatted and prepared for printing. When resizing images, be careful that they do not become distorted or pixelated.

  * As with any visual element, do not overuse images. Too much clutter distracts readers and may ultimately make the information harder to process.

Tables

Tables are often used in technical documents to make information easy to scan and process. Tables are comprised of columns and rows, which together form cells that contain specific data values. Tables allow readers to compare variables easily, and they can efficiently relate large sets of numbers or statistics much more quickly then sentences can. For instance, Table 1.1 shows the changing enrollment rates at a university. The table allows readers to quickly understand the enrollment trends over the past five years.

Year |  Total Student Enrollment  
---|---  
2009 | 25,698  
2010 | 26,487  
2011 | 27,901  
2012 | 30,576  
2013 | 31,787

Table 1.1: Student enrollments

For Further Reading

Alred, Gerald J., Charles T. Brusaw, and Walter E. Oliu. _Handbook of Technical Writing_ 10th Ed. New York: St. Martin's, 2012. Print.

Rude, Carolyn and Angela Eaton. _Technical Editing_ 5th Ed. Boston: Longman, 2011. Print.

Williams, Joseph M. _Style: Toward Clarity and Grace._ Chicago: U of Chicago P, 1990. Print.

Chapter 2: Proposals

What is a Proposal?

A proposal attempts to persuade readers that the proposed material is to their benefit, usually because it offers a solution to a problem or provides a good or service. Proposals offer detailed descriptions of the problem that needs to be addressed and persuasive arguments in favor of a suggested solution.

Proposals can be solicited or unsolicited and can be written for an internal or external audience. Solicited proposals respond to a request for proposals (RFP), whereas unsolicited proposals are written and sent without request, usually as a suggestion. Internal audiences include people within the same company or organization as the proposal writer, while external audiences include people outside of this group, usually clients or funders of the proposal writer's organization. The type of proposal written depends on how these criteria intersect.

  * ** Solicited Internal: ** Proposals written to solve a problem posed by someone else within the company. They are usually written to solve some organizational problem or policy recognized by the person making the request.

  * ** Unsolicited Internal: ** Proposals written to suggest solutions to problems within the company perceived by the writer of the proposal.

  * ** Solicited External: ** Proposals written to fulfill a need for a product or service as requested by a client outside of the company. They are often written in response to an organization's request for proposals (RFP).

  * ** Unsolicited External: ** Proposals written to suggest a solution for a perceived problem within another organization.

Solicited proposals are almost always written in response to an RFP, which lays out the problem that needs to be solved and asks for proposals from qualified organizations. RFPs also include any requirements of the proposed solution, such as criteria for success and budgetary or technological considerations. The formatting requirements of the proposal, such as length and content organization, will also be included within the RFP. Figure 2.1 shows the content and format requirements specified by an RFP. When responding to an RFP, writers must follow the guidelines outlined in the RFP, as an improperly structured or formatted proposal will likely get rejected, often without even being read.

Figure 2.1: Content and Formatting Requirements in a Request for Proposals

Proposals can be broken down even further into the categories of formal and informal. As a general rule, the more money, time, and effort it will take to follow through with a proposal, the more formal the proposal needs to be.

Why Do People Write Proposals?

Companies send proposals to address a potential client's specific need, whether it is a lack of a particular good or service or a required change of policy and practice. Proposals work to not only bring awareness to a given problem, but to lay the groundwork for the solution. Proposals highlight and explain a problem, outline its solution, and then describe the resources that will be necessary to start fixing the problem. Proposals are often used to attract new clients to a particular business or to get money for research or implementation. Proposals are often written by researchers, technical communicators, managers, human resource personnel, and entrepreneurs.

Who Reads Proposals?

Funders read proposals to decide who will receive the money they are offering. Decision makers also read proposals to decide which solutions to implement. Ultimately, the audience evaluates the merit of the proposal. They decide whether the proposal succeeds or fails. A proposal must demonstrate that the needs and concerns of its readers have been taken into full consideration. When proposals are unsolicited, writers must convince the reader that a problem exists that needs solving. Writers must also remember the corporate status and knowledge of the reader. The person reading a proposal will likely be an upper-level decision maker. The proposal will also be important to the people in charge of implementing the suggested changes.

How do I Write a Proposal?

While the contents of a proposal can vary widely depending on its purpose, most proposals share several common elements:

  * Abstract

  * Introduction

  * Identification and Discussion of Problem

  * Presentation of Solution

  * Budget

  * Schedule

  * Conclusion

The abstract provides an overall summary of the proposal. It should contain the essential elements of the proposal, especially the problem being addressed and the solution to that problem. The abstract can include or be replaced by an executive summary, which is similar to an abstract but provides a longer summary aimed specifically at the upper-level executives who will use the proposal to decide on a course of action.

The introduction engages the reader to take action. Not every proposal gets read from start to finish, and the introduction must convince the reader to keep reading. Unlike the abstract, which will contain condensed information about the entire proposal, the introduction must capture the readers' attention and keep them interested in the problem that the proposal offers to solve.

Make sure to identify the problem. Proposals can address known problems or identify new ones, but they always need to clearly lay out exactly what the problem is. The establishment of the need for a solution to a perceived problem is critical. This section should illustrate the size, scope, and severity of the problem. These descriptions must be specific: for instance, a non-profit grant should avoid vague descriptions such as "Our city contains many poor children" in favor of a more concrete needs descriptions like "43% of 6-12th graders qualify for reduced or free school lunches." If the proposal responds to an RFP, that RFP will describe the problem or need. These descriptions will provide language and details that can help writers develop their own descriptions of the problem. Unsolicited proposals should describe the problem without appearing condescending to those who may not have noticed the problem in the first place.

Make sure to present a solution. This section is crucial and will likely make up the meat of the proposal because the suggested solution has a strong influence on the acceptance of the proposal. If the proposal markets a product or service, this section describes that product or service. If the proposal suggests changes in policy, this section lists those changes and the advantages of the suggested policy. Writers must specifically lay out the advantages of the suggested solution and describe the steps to see it through. The section must be thorough, persuasive, and credible. If the solution is clearly laid out and carefully considered, it appears more professional and ultimately more feasible.

The budget section will likely be one of the most important to readers, as they will be called upon to spend their resources of money, time, or manpower. Readers will appreciate the effort spent making sure that the budget for the proposal is thorough and comprehensive. Writers must account for every potential expense in the execution of the proposal, including materials, salaries, equipment, and facilities. Budget information should be easy to find and easy to read, as readers will likely look at it early and return to it repeatedly. The budget must also be realistic. If the proposal makes unfeasible promises about the budget, these claims will hurt the proposal's credibility. If the proposal is accepted with an unrealistic budget, the unaccounted costs can be extremely damaging to the organization, which will end up covering the cost overruns out of its own pocket.

Include a schedule. Closely related to the budget, this section outlines the time frame of the proposed actions. This is where questions are answered about when the proposed action will take place, how long it will take, when each stage will start, and when the project will end.

Write a conclusion which summarizes the proposal. The conclusion must make a strong final impression on the reader. Much like the abstract, the conclusion will be a summary of the proposal, but the conclusion has the added benefit of referencing details from within the body of the proposal. The conclusion of a proposal is the best place to stress the significance of the points touched on throughout the proposal. It should be strategically redundant, reiterating key information, such as costs and benefits, so it is easy to find and sticks with the reader.

Throughout each section, the proposal needs to educate its readers about a problem they might not be familiar with, present a solution, and persuade readers that the solution proposed is the best. A proposal is not quite a sales pitch, yet not quite a report either. It falls somewhere in between.

Making a proposal visually appealing is important. Images and diagrams can make the information easier to digest, so they should be used effectively to help the reader connect with the proposal's suggestion. Images, tables, charts, and diagrams should also highlight the proposal's most important information so that readers can easily find and understand it.

The text of the proposal itself should be easy on the readers' eyes. Long blocks of text should be broken up into smaller chunks with eye-catching headings. Long lists should be broken down into easier-to-read bullet points, rather than being buried within thick paragraphs. The easier the text is to read and process, the more likely it is to stick with readers.

Sample Proposals

Texas Solar Power Company

Low Income Wind Power Project (via The Grant Doctor)

USDA Sample Proposal

Kurtzweil Sample Grant Proposal

For Further Reading

Oklahoma University Proposal Development Resources

#  Chapter 3: White Paper

##  What is a White Paper?

The term " _white paper"_ originally referred to an official government report written to inform readers of a particular problem or issue and potential solutions. Though they are no longer confined to official government use, white papers still carry their traditional objective and authoritative tone. However, the white paper often serves to advocate for one particular solution over others by subtly persuading the audience of the viability of the proposed solution. While white papers share many similarities with proposals, they do not respond to Requests for Proposals (RFPs) and they rarely include detailed budget or schedule information. There are many ways that a white paper can be tailored, depending on the situation, but the typical white paper runs between five and twenty pages. White papers that exceed this length often risk losing the attention of the reader.

Despite the many variations inherent to these documents, they often share a few basic similarities. They are rarely read from cover-to-cover; therefore, they include headings to allow for accessible skimming. Most white papers share other general formatting guidelines. They typically open with an overview of the problem and proposed solution (the main argument), and then go on to list the key points that back up that argument. White papers then provide examples of how the proposed solution/s worked in previous and similar situations. Finally, a white paper provides the reader with a summary, which restates the initial argument and summarizes the conclusive evidence which supports it.

##  Why Do People Write White Papers?

As explained above, in their traditional context, white papers are used to officially inform an audience of a problem or issue. However, some companies use white papers to claim a position in their respective market space or to gather leads about a particular subject. This is accomplished by educating and informing the reader (or client), with the intention of either building credibility or influencing a future decision. According to Gordon Graham of thatwhitepaperguy.com, "On a strategic level, white papers fit into the widespread trend of 'marketing with content'... This model acknowledges that skeptical prospects are hungry for a vendor who will serve as a trusted advisor, not just a peddler of their wares."

However, a white paper is NOT an overt sales pitch, nor should it be formulated and presented as one. Though often created for marketing purposes, the persuasive undertones of the pitch are buried underneath what appears to be an empirically-grounded, informative document. Often confused with news releases, white papers are similarly often sponsored by a company. However, unlike news releases, white papers often take the form of solution-oriented, subtly persuasive essays about a technological innovation, emerging methodology, service or product that a company wishes to present to a potential or existing client.

##  Who Reads White Papers?

In addition to being read by government officials and administrators, white papers are also commonly read by financial and corporate executives, product user representatives, and business and IT managers. Graham reports that some IT managers read upward of fifty white papers per year. Often, in larger corporations, committees and other collective decision makers all read white papers to get everybody 'on the same page' before deliberating about a major decision.

Audience members also read white papers for helpful advice and insight about market trends, new technologies, or effective sales strategies. These audience members seek value-added content that will help them improve their personal or company performance.

##  How Do I Write a White Paper?

The first and most important component of writing a successful white paper is understanding the audience. It is important to consider the target audience when writing any document, but catering white papers to their audiences often requires a greater level of diligence and specificity due to the unique specializations/interests of the potential readers. Figure out what problems these readers face and their criteria for evaluating solutions. White paper writers can understand their audience by researching the decision-making roles the audience members play in the company or agency for which the document will be written. Writers can also ask sales staff or company representatives what problems and concerns potential clients frequently raise.

Remember, the primary objective when addressing the specified audience is to deliver useful information. The format used to deliver that information must correspond to the reader's attention span and need for detail. White paper writers commonly use two formats to get reader attention. The first is the classic white paper. The classic white paper is a narrative, which is at least five pages long. It delivers detailed need-to-know data in organized chunks, which is easily navigated by the readers. This classic white paper follows the traditional problem/solution format.

The second format is the less-traditional 'numbered list' white paper. This format grabs the reader's attention from the beginning and attracts a higher-energy/shorter attention span audience. This tells the readers, immediately, that they do not need to wade through a highly-detailed document. Instead, they just need to skim a few easily-accessible main points to get the white paper's message. Many executives and other busy, on-the-go readers have too little time and too much work to carefully read through a lengthy document, so this format often appeals to them. This format leads off with an engaging hook like "5 Ways to Boost Earnings Potential" or "3 Ways to Streamline Inventory Management."

###  How to Write a Classic Whitepaper: Seven Steps

** Step 1: Establish the purpose (problem/solution) and audience in detail **

Determine exactly who your white paper will target. Make the audience as specific as possible; instead of just targeting "iPhone Users," find a specific audience like "IT Sales Reps who Engage in Social Media Marketing via their iPhones." Finding a specific audience allows you to provide more detail and address their needs more specifically.

** Step 2: Gather data **

This data can come from many different sources, such as market-research documents, customer representatives, and online forums, blogs, and product reviews. But the most effectively leveraged sources are often interviews collected from the customers themselves, including key people in the company and members of your target market. These opinions and insights help formulate the best possible argument for your proposed solution, because you can tailor your solutions directly to your customer.

Another excellent way to gather data is through market requirement documents (MRDs), which elaborate the customers' wants or needs for a particular service or product. You should also look for any publicly-available data about your competitors. Having details about the competition allows you to play to your competitor's weaknesses. However, it is not typically necessary or prudent to use the competitor's name in the document.

** Step 3: Write your first draft **

White papers work best when they are positive and solution oriented. Avoid taking a negative tone, as it only serves to distract and alienate your readers. Though you may be writing to redress a problem or issue, using the white paper to point the finger at those responsible will only draw your readers' attention away from your solution. Metaphors must be used responsibly, but they serve as a great way to make a very specific point and appeal to a much broader audience when used appropriately. Above all, stay on topic.

White papers are often structured around four organized chunks of text:

  1. General Overview: a semi-detailed presentation of your initial argument
  2. Main Points: the main arguments of your white paper, including facts, figures and statistics that back up your argument. (After these points, explain why your solution/product/service is the best, if applicable)
  3. Examples: provide readers with examples of how your solution has been successful
  4. Conclusion: summarizes your argument with supporting data one last time

** Step 4: Review your first draft **

As you review your draft, find a second or third pair of eyes for your document to provide you with some objective feedback. Ideally, these individuals should have expertise, like relevant sales experience, that can provide technical insight. Use this feedback to your advantage in the second draft.

** Step 5: Write your second draft **

This should be thoroughly revised based upon the feedback you received on the first draft. This draft should also be more streamlined and concise. You should also try to strengthen the case for the offered solution.

** Step 6: Review your second draft **

If possible, this draft should be reviewed by someone from your target audience, such as a prospective customer. The intimate knowledge this individual has of the problem/issue/need will help ensure that you are speaking the customers' language and do so consistently throughout the document. This person can point out instances when you have gotten off topic or obscured your argument with excessive detail.

** Step 7: Write and review your final draft **

This final draft should be a well-organized, visually-appealing document that presents your argument, proof, and examples clearly and ends with a strong conclusion.

###  How to Write a Numbered List White paper: Three Steps

** Step 1: Pick one event or outcome that your audience wants to either avoid or attain. **

Figure out a problem that your audience faces or a goal they want to attain. Use this idea to develop a catchy theme, such as, "Logistics Pitfalls to Avoid" or "Ways to Boost Sales Revenues."

** Step 2: Use a number. **

This number needs to be based upon how much you can expound upon your topic, for example, "Five Logistics Pitfalls to Avoid" or "Three Ways to Boost Sales Revenues." This would be a good time to add a subtitle to cater the document to your reader, like "Three Ways to Boost Sales Revenues: A Guide for Marketing Directors and Sales Managers."

** Step 3: Fill in the list. **

Use your best content to drive each point home, using facts and statistics to enforce your argument. This style does not need to be as cohesively developed as the classic white paper; therefore, it allows you to get to the point a bit quicker. Do not hesitate to change the number of list items halfway through the writing process; the great thing about this format is the flexibility it provides. It allows you to explain more material without having to build each point from scratch. Adversely, one of the greatest drawbacks about this format is how frustrated the audience gets when your list of points wastes their time. You must keep it interesting and relevant to make this approach work effectively, so be sure your points are strong and that your argument is well reinforced.

##  Sample White Papers

Samsung White Paper

Six Steps for Building a Long-Term Strategy for Mobile: Technical Considerations

Eight Rules for Creating Great White Papers

##  For Further Reading

Writing White Papers

Eight Tips for Writing White Papers

#  Chapter 4: News Release

##  What is a News Release?

News releases (also called press releases) summarize potentially newsworthy events for media outlets. A company will disseminate a news release (a concise news story, usually 1-2 pages) to various media outlets to encourage them to cover company news and events. The three basic purposes of news releases are

  * to inform the media about an event or product release (in hopes the information will be publicized),

  * to let the media know about your business in hopes that a reporter will cover your business

  * to help promote your business's Internet presence (direct readership publicity) through blogs, websites, and social networks.

Effective news releases capture the attention of the media. In order to appeal to a media outlet, you must think like one. Do not necessarily think about what is important to your organization or an individual newspaper reader; think about what is important to the media. Media outlets are constantly competing with each other, trying to have the most interesting and updated news to interest their audience. Frankly, if that media outlet does not feel its viewers will be interested in your story, they will not run it.

##  Why do People Write News Releases?

News releases are key in building and maintaining successful relationships with the media and community. Not only do they inform the public about positive future events or projects, but they also serve as damage control for events that have already transpired and could prove detrimental to the company's reputation.

In fact, the first news release came about during a corporate crisis. On October 28, 1906, at least 50 people died when a train from the Pennsylvania Railroad Company jumped a trestle near Atlantic City, New Jersey, and fell into the Thoroughfare creek. Ivy Lee — widely considered the father of modern public relations — represented the Pennsylvania Railroad Company. Lee encouraged the railroad company to issue a statement and provide journalists with a train ride to the scene of the accident. The _New York Times_ was so impressed with this innovative approach to distributing information on a corporate level that they printed the release as the "Statement from the Railroad." After weeks of dissemination, the article had reached newspapers all over the country, and media were praising the Pennsylvania Railroad for its honest and open explanation. The practice has been a core part of communication between corporations and the media ever since.

News releases also help organizations maintain healthy relationships with the media. This is because of the symbiotic relationship between the media and public relations practitioners. Simply put, both have a mutual need for each other – public relations practitioners needs to get the word out about their company, and the media outlet needs a story to run.

##  Who Reads News Releases?

General audiences rarely read news releases (though this is changing now that companies post news releases on their websites). Instead, reporters, editors, and media outlets read news releases while looking for stories to cover. As previously stated, news releases usually provide information that eventually reaches a mass audience. Companies are usually not able to reach these audiences on their own. The media broadcasts this information to its audiences for them. But just because a news organization receives a press release does not mean it will disburse the information. The release has to appeal to the news entity's gatekeeper. The _gatekeeper_ – usually an assignment editor, news director, reporter, or Webmaster – decides what is newsworthy and what is not. If the gatekeepers do not find the press release appealing to their audience, they simply will not use it. They want to find the stories that will most peak the audience's interest. Just because the information may be interesting to the company does not necessarily make it interesting to the public. And if it is not interesting to the public, it certainly is not interesting to the media.

How do you determine what is newsworthy and what is not? As a communicator with public relations duties, you must determine what will peak the gatekeeper's interest. _Media Writing: Print, Broadcast, and Public Relations_ , by W. Richard Whitaker, Janet Ramsey, and Ronald Smith, states that potentially newsworthy information usually falls into one of these categories: events, trends, community relations, policies and governances, issues, and personnel.

Imagine you work for a software engineering firm. A newsworthy _event_ may be the ground-breaking ceremony for a new facility in town. A _trend_ that may peak the public's interest would be a study on why people prefer PCs over Macs (or vice versa). A newsworthy _community relations_ story would be a sponsorship that provides laptops to a local high school. _Government policies_ for collecting data on technology users would be interesting to audiences as well. _Issues_ such as putting a stop to online security breaches are interesting to audience members because they could be affected. Personnel issues might include the hiring of a new CEO.

Public relations experts often argue that an event or trend has to fall under one or more of these _news values_ , or criteria, that determine the desirability of a potential news story for a certain media outlet:

  * **Impact** : The greater influence that an event or trend will have on the lives of the viewing audience, the more newsworthy it is. For instance, if a company is bringing in 500 more jobs into the area, the television audience in the community will want to know so that they can apply for the jobs.

  * **Timeliness** : The more current a news story is, the more appealing it will be to the news media. News media will not cover a story, no matter how interesting it is, if it has no ties to the present, very recent past, or very near future. For instance, if a company is hosting a job fair two months from now, the media will not cover it until closer to the event, usually no more than two weeks ahead. You also do not want to send out a press release the day of the event because media outlets may be too busy with other stories to put it in their outlet that day.

  * **Proximity** : The closer in geography a story is to a viewing audience, the more newsworthy it is.

  * **Human interest:** These stories try to invoke emotions, such as sympathy or compassion. Stories about soldiers surprising their loved ones by coming home, dogs being reunited with their families, and people doing humanitarian work are all common human interest pieces.

  * **Conflict:** Opposition by two or more people, organizations, or forces almost always appeals to a news audience. When it comes to news stories, the more drama, the better.

  * **Bizarreness** : This is anything unusual or unbelievable which will likely attract attention.

##  How Do I Write a News Release?

Since the inception of the Internet and social media, the way news releases are distributed has changed. Still, there are some common elements that a news release must include, no matter if it is a hard copy printout, Portable Document File (pdf), an e-mail, or a social media post. According to Whitaker et al., every news release must include these elements:

  * **Heading:** The first few lines of the news release are designated for the name and address of the sending organization, along with the name and contact information of the writer of the release or another person within the organization whom the media can contact for more information. The last line of the heading should include the date the information should be disseminated to the public; it may also simply state _For Immediate Release._

  * **Headline:** Press release headlines resemble headlines in newspaper articles, only they also includes the name of the organization. The headline sums up the point of the event or trend in a few words so that journalists know what the news release is about. For example, the headline might read _News from Northrop Grumman – New Missiles Facility Will Bring More Jobs to Huntsville._

  * **Summary News Lead:** News releases are usually structured with the most important information on top with inferior details towards the bottom, like an inverted pyramid. The summary news lead includes the Who, What, When, Where, and Why of the story, so that journalists do not have to dig to find that information. All of these elements may not appear in the summary news lead, but the most important two or three must be in it.

  * **Benefit Statement:** This is usually directly after the news lead where the importance of the story to the public is explained. This is the selling point for the media because it answers the question, "Why should our audience care?"

  * **Action/Info Statement** : The last absolutely essential part of the news release is the action/info statement. This part explicitly states what action the audience can take in response to the story or where they can find more information about the organization that issued the release. Whitaker et al. states that this is meant to be helpful rather than directive and is usually phrased _Additional information can be found at...._ instead of _Call ________ for more information_.

  * **Secondary Details:** Less important details may follow all of the above elements (though the action/info statement may still be at the bottom). Make these details very sparse because journalists usually do not read this part. Instead, you may add this information to the company website. Too many secondary details make the news release longer than it needs to be, and in a hectic newsroom, editors may not take the time to read this information.

  * **Background Information:** This information puts the benefit statement into context. It explains the environment of the story behind the news release. Like the secondary details, it should not be very long.

  * **Organizational Identification:** Whereas background information provides context to the relevancy of the event or trend, the organizational identification provides more information on the organization itself. Some writers add this paragraph as a standard identifier on all of their communications.

  * **Footer:** This is a visual signal that indicates the end of the release. It may be written as a series of hash marks _(###)_ or simply state _((END))_ in all capitalized letters between two sets of parentheses. For a printed release, if information continues on to another page, then a 'more line' may appear at the end of the preceding page written three times, separated by dashes, and between double parentheses, like this: _((more-more-more))_.

  * **Note to Editors:** Information for editors or journalists that is not meant to be shared with the public is added here. For instance, if media needs to register ahead of time, if there is a special entrance at the event for photographers, or if there are specific interview times, that information needs to be stated in this note.

Beyond the basic elements of a news release, effective press release writers follow certain practices in order to ensure clear communication to the media. Just like any other technical document intended for a non-technical audience, making the information easy to read is key.

  * **Proofread:** Not only is it important to make sure that everything in the press release is grammatically correct, but it is also important to double, even triple check all of the information. Remember, this information will be disseminated not only to the media outlets, but also to their audiences. If the wrong information is sent out, it could negatively affect the organization's credibility and put a damper on relations with media outlets. Remember, they do not want to put out false information to their audiences any more than your organization does.

  * **Don't Use Jargon:** Jargon is meant for intra-industry use only. It is okay to use with other technical professionals; however, when it comes to journalists and a public audience, it is better to assume that they know absolutely nothing about the industry, so use plain language so the intended audience is not excluded.

  * **Write Professionally:** Using slang is the quickest way to destroy credibility. It also makes the news release seem more like an advertisement than news. Also publications may run the information in the news release very little modification. Writing professionally includes not using slang, excessive exclamation points, or sensationalistic writing.

##  Sample News Releases

Kindle Fire HDX Press Release

Zoo Announces Elephant Pregnancy

Revitalized Taste of Chicago Profitable for First Time Since 2007

##  For Further Reading

How to Write a Press Release that Gets Noticed

How to Write a Great Press Release

# Chapter 5: Software Documentation

## What is Software Documentation?

Software documentation describes the written material that accompanies software (computer programs). The term "documentation" may sound complicated, but really, it refers to descriptions that convey how the software works and how to use it. In other words, software documentation documents the process of writing or using software. Programmers write one kind of documentation as they create the software. Technical communicators write another kind of documentation—user documentation—that instructs users about how to use the software. User documentation often comes in the form of user manuals. Some kinds of user documentation, such as online help, are not covered here, but the same writing principles can be applied to all forms.

## Why Do People Write Software Documentation?

Effective documentation is essential for users and software developers. Without clear and appropriate documentation, software becomes frustrating and difficult to use. Effective documentation makes software more useful because it can help developers during the development process and users when the product reaches the market. Developer documentation improves communication during the development process by describing how the code works. The result of good communication is better-designed software. Well-written software documentation helps users to accomplish specific tasks. Users cannot accomplish tasks with software that they do not understand.

## Who Reads Software Documentation?

There are two main audiences for software documentation: users and developers. User documentation is practical and helps users to accomplish tasks using software. Developer documentation is more technical and includes more technical details about the software that might not matter to end users. Think about who will be using your product so that you can figure out how to meet their needs.

When determining your audience, you need to consider the reading strategy of the users. Users typically consult software documentation when they encounter a problem. Even then, not all users read documentation in the same way. Users search for information three different ways:

  1. Reading the software documentation from start to finish before starting a task

  2. Starting from the first task and completing each task as the steps are described

  3. Skimming software documentation to find the part they think will answer their question

Very few users read documentation from start to finish. Most users search for help by skimming; these users are the most difficult to accommodate. However, if you follow the advice in this chapter about "Writing Task-Based Headings," you will better understand the importance of writing documentation to match the needs of users.

## How Do I Write Software Documentation?

Developer and user software documentation require different writing approaches because different audiences read them. Developers and users interact with the software in different ways, so they need different types of documentation.

Software documentation for developers is highly technical because it is closely connected to the source code (the coding language). Essentially, software development documentation is composed of notes, written by programmers, which explain certain sections of the source code and how those sections work. Programmers either embed these _notes_ within the source code itself as comments or store them in a separate document.

User documentation, on the other hand, is less technical. It should be designed with users' needs in mind. Since users do not always understand technical language, software documentation should be written in a simple, organized, and easy-to-follow style. The most important thing to remember when writing user documentation is always to think about your potential users and their needs. Consider what tasks the users will want to accomplish with the software and design the documentation or user manual to match those goals and tasks. Task-based headings, clear explanations of terms and instructions, and effective incorporation of visual elements are the most important strategies a technical writer can use when writing user documentation.

### Determining the Audience

The best way to start creating effective user documentation is to learn about the users. Interview users to determine their product knowledge and expectations for product performance. Peter Vogel, an influential computer designer who wrote Read the Manual!, argues that audience analysis for user documentation should gather four major items of information:

  1. User knowledge on the subject

  2. User knowledge of similar software products

  3. User knowledge of your software product

  4. User tasks or goals in using the product

Learning how much your audience already knows will help make your documentation concise. Do not include information that your audience either already knows or will never use. Instead, documentation should be task based, chunking its information into specific tasks that are easy for users to find. Include only the tasks the users will likely want to accomplish so that users will not have to search through extra pages of a manual to find the information they need.

### Planning the Parts of a Software Manual

A typical software manual contains many parts. Some parts, such as restrictions of use and copyright information, are required by law. Other parts, such as the main body of the manual, will contain the most useful information. Other parts, such as the table of contents, help the user navigate the manual. According to David Tuffley, author of _Software User Documentation: A How to Guide for Project Staff_ , most manuals include eleven parts:

  1. ** Title Page: ** Contains document title, project name, version number, release date, and other similar publication information.

  2. ** Restrictions: ** Contains legal restrictions for using the software.

  3. ** Warranties: ** Contains warranty information for faulty software.

  4. ** Table of Contents: ** Contains a detailed list of chapters, headings, sections, or other relevant divisions of the Body, along with page numbers.

  5. ** List of Illustrations: ** Contains entries for each illustration, along with page numbers.

  6. ** Introduction: ** Explains the software, describes the audience and purpose of the documentation, and offers advice on using the documentation and reporting problems.

  7. ** Body of Document: ** Contains the bulk of the document and describes tasks and how to complete them.

  8. ** Error Conditions: ** Lists error messages/codes with descriptions of what caused the problem and how to fix it.

  9. ** Appendixes: ** Contains sample files, input and output codes, and other technical information that does not fit within a section of the body.

  10. **Bibliography:** Lists any sources or publications quoted or referenced and may include publication information for further reading.

  11. **Glossary:** Lists and defines acronyms and abbreviations.

Some of these parts may be optional depending on the assignment, and other additional information (such as specifications and installation information) may need to be included as well.

### Writing with Task-based Headings

To create effective user documentation, divide the body into sections based on specific tasks and provide users with three basic elements in each:

  * Context: When will users need the feature, command, or function discussed?

  * How-to: What steps will users need to take to complete the task?

  * Feedback: What outputs should the software display when tasks are complete? What errors may occur?

The body of the document needs to be well-organized to help users find information. Users want to accomplish tasks. Most users do not use software because of a desire to try out a new program. (Some do, of course, but they're likely the kind of user who doesn't need a lot of instruction.) Instead, most users use software because they want to _do_ something. They want to produce a document or a database—not to use a word processing program or a database management system.

Task-based headings are a more efficient, user-centered way to organize content. They are an alternative to organizational patterns based around the structure of the software. A user manual organized by menu, for example, is unhelpful (Vogel 58). In a menu-based organization, sections of the documentation are divided according to where the commands are located within the program, instead of being divided according to their purpose. For instance, all commands under the File menu would be in one section, and all the commands under the View menu would be in another section. This organizational pattern is least helpful since users will likely struggle to find a command unless they already know where it is located. Suppose user wants to create a new document. It will be easier for the user to find the information under a section entitled "Create a New Document" than to find the information under a section titled "The File Menu."

Once you have gathered information about your audience, you should be able to determine what kinds of tasks they want to accomplish. Organize material around these tasks and group similar tasks together. Your material should include several items of information. Start by telling users the context of the task. When will they need to use the Table Properties menu? For example, you might write, _Use the Table Properties menu to edit the appearance of the table, including the size and cell alignment_. Then, give users the sequential steps they need to accomplish the task. In addition to giving users the steps, tell them what to expect as they go through the process. Will a dialog box appear after they click the command? If so, tell them. This feedback will help users chart their progress and know they have performed tasks correctly. If time and resources permit, also address potential problems the user might encounter, such as error messages. These error messages may be housed in a separate section, if time and resources permit.

Remember, give users context, how-to information, and feedback for each task-based section.

### Explaining Your Terms

Since user documentation is written for users, not technical experts, explaining unfamiliar terms is important. The number of terms that need to be explained depends on the knowledge of the audience. If the documentation is designed for technical users in the field, some technical jargon may be acceptable, but if the documentation is designed for everyday, non-technical users, jargon needs to be explained.

If you are not sure how much knowledge a user has, then remember this rule: assume that readers know how to use a computer but not necessarily how to use the program. For example, users will probably know what a File menu is since File menus are features of many computer programs, but they may not know how to use Format Painter.

Obviously, it would be wasteful and time-consuming to define every term, so prioritize and include only the terms most crucial to the document. Just ask yourself, "What terms or concepts _must_ users understand in order to accomplish their tasks?"

Figure 6.1 shows a page from the manual for Freemind.pdf), an open source mind-mapping software program. The page labels parts of the software interface so that users can find them.

Figure 6.1: A manual page labeling parts of a user interface.

Figure 6.2 shows a section of the manual for GlassFish, an open source application server. Notice that the manual introduces the task "Performing a Silent Mode Installation" by defining "silent mode" as "a non-interactive installation based on user-defined parameters captured in an answer file." This definition will help users decide if this installation approach suits their needs.

Figure 6.2: A manual page defining the term "silent mode."

### Writing Clear Instructions

Clear writing makes documentation easier to use. Since users are probably already frustrated by a task when they approach the documentation, unclear language will only frustrate them further. To clarify your writing, use imperative verbs, include every step, and be specific in describing the steps.

Use imperative verbs to tell the reader how to perform the steps of the task. Compare the two statements below:

Weak: The user should click the mouse.

Strong: Click the mouse.

The second version is clearer because it uses fewer words to make the same point and it tells users exactly what they must do. Imperative verbs clarify the steps for the user.

Include every step, even if the step seems self-explanatory. Telling users to click a command is unhelpful if they do not know its location.

Weak: Click the Print command.

Strong: Click the File Menu. Then, click the Print command.

The second version is stronger because it includes _all_ of the steps that must be performed.

The examples above illustrate a third principle of clarity: be specific in describing the steps. It may not be necessary to specify _left-click_ everywhere, since left-click is the default click method for most computer users; however, when a step varies from the default method, state it explicitly. If users need to right-click to access a command, tell them. Usually, a left-click and a right-click in the same place do entirely different things. Don't make users guess. Tell them _exactly_ what they need to do!

### Using Visual Elements Effectively

The appropriate use of visual elements helps users find what they need and accomplish tasks more effectively. Screen images show users the location of commands and offer feedback about how the screen should appear as they complete steps. Other visual elements include formatting techniques that prioritize information for a reader, such as bullets, boldface type, and color.

### Using Screen Images

The old saying "A picture is worth a thousand words" is especially true when referring to user documentation. Although few would argue that images alone can replace text instructions, research shows that incorporating screen images into user manuals speeds up training (van der Meij 294). It is easier for users to find the appropriate command if they are shown an image of its location on screen, rather than only a description of its location.

At least one study suggests that the most effective visuals are full-screen images placed to the right of the accompanying text on the page—or on the screen, for electronic documentation (van der Meij 301). The instructions should appear on the left side of the page, and the images that show the actions described should appear on the right side. If possible, use full-screen images to illustrate what the display will look like at various points of the task. Additionally, refer to the content of the screen shot by name (i.e. "The File Menu will appear" instead of "The screen below will appear"). Screen shots may need borders to keep them from blending in with the rest of the page.

To make visuals even more effective, use techniques to indicate which parts of the images are relevant to the task at hand. Signaling techniques are called _cueing_ , and different types of cues include visual indicators such as "hairlines, circles, call-outs and blurring" (van der Meij 296). _Hairlines_ are fine lines that point to specific elements on a screenshot. Usually, text accompanies the hairline to label the element that the hairline indicates; that text is called a _call-out_. Writers can also blur out unimportant parts of an image to emphasize the most important areas. Any of these indicators can make the visuals more effective, but always be sure to highlight the appropriate element.

Figure 6.3 shows a page from the manual for Freemind.pdf), an open source mind-mapping software program. Notice that the page includes a screen shot of the relevant dialogue box. The manual references and labels the screen shot so that users can easily understand it.

Figure 6.3: Freemind Software Documentation

### Using Formatting Techniques

Highlight important information for users by utilizing formatting techniques. Use bulleted or numbered lists to show the sequence of steps.

Weak: Click and drag to select the cells, click Format as Table, select the desired style, and when the table comes up, click OK.

Strong:

  1. Click and drag to select the cells
  2. Click "Format as Table"
  3. Click on the style you want to apply
  4. A dialog box appears: Click "OK"

The numbered list makes reading easier because it breaks down the steps for users. The list also leaves white space on the page. White space separates information on the page and is easier on the eyes. Put key terms and important parts of the step in quotation marks, boldface type, italics, or color.

In summary, remember that user documentation for software is just that: _user_ documentation. Keep users' needs in mind at every stage of the writing process. Organize the material by task to enable users to find what they need; write in simple, clear language; and use full-screen images, cues, and formatting techniques to illustrate steps to the users.

## Sample Software Documentation

GIMP Manual

 Open Office Getting Started Manual

 Adobe InDesign CS5 Help

 Ubuntu Help

## For Further Reading

Tuffley, David. _Software User Documentation: A How To Guide for Project Staff_. CreateSpace Independent Publishing Platform, 2011. Print.

van der Meij, Hans. "The Role and Design of Screen Images in Software Documentation _." Journal of Computer Assisted Learning_ 16 (2000): 294-306. Print.

Vogel, Peter. _Read the Manual!: The Little Book on How to Write So You'll Actually Get Read_. Ontario: PV&H Information Services, 2009. Print.

# Chapter 6: Procedures

## What Are Procedures?

The terms "procedures," "policies," and "instructions" are often used interchangeably in texts and conversation as if they are the same thing. While they may seem quite similar, there are minute differences between the three. The Encyclopedia of Telecommunication defines a procedure as "a document written to support a "Policy Directive." In addition, procedures specify the "Who, What, When, and Why by establishing corporate accountability in support of the implementation of a "policy" ("Procedure"). Procedures also include work instructions that establish the "how." In short, procedures are the steps taken to achieve a particular result. Good procedures are easy for users to understand and follow.

##  Why Do People Write Procedures ?

Procedures are important in many aspects of business, law, and everyday life. It is difficult to successfully complete any task without well-written procedures. Without established procedures, executing daily tasks could potentially cause chaos and frustration. Many organizations make the mistake of creating too many procedures because they believe businesses need a huge library of procedures. It is important that organizations establish procedures to help employees accomplish specific tasks and not just for the sake of having a procedures manual.

Procedures help users by

  * Listing steps for operating something.

  * Listing steps for assembling something.

  * Providing information about organizational protocols or policies.

  * Listing steps for troubleshooting, repairing, adjusting, or maintaining something.

It is impossible to write down everything a person should know in every possible situation. Therefore, it is acceptable to forgo creating procedures for some tasks. However, some topics or tasks will require clarification whether they are universally known or seldom utilized.

Procedures need to be provided if the described task is

  * routine
  * lengthy
  * complex
  * frequently changed
  * dangerous
  * governed by specific laws or regulations

While procedures are often used in conjunction with policy manuals within organizations, they can be individual documents as complex as computer programs or as simple as memos. Figure 6.1 shows The State of Vermont's procedures for keeping employee files; this procedure ensures that all personnel files are consistent and complete.

Figure 6.1: State of Vermont Personnel File Procedures

## Who Uses Procedures?

Procedures are written for a variety of situations. Therefore, the audience will differ depending upon the type of procedure that is being written. Procedures are utilized in business organizations, law, computer programming, and more. Everyone uses procedures at some point. The reader may be an employee, manager, customer, student, patient, or CEO.

### Procedures in Business

In business, procedures are used in the areas of governance, compliance, communication, continuity and education ("Writing Policies and Procedures").

  * Governance: to maintain control. Procedures can describe the management philosophy of the organization.

  * Compliance: to comply with best management practice standards. OSHA, FHA, and the USDA, for example, are constantly adding and changing laws and companies must comply with these changes.

  * Communication: to provide access to employees, customers, and stakeholders. Procedures, along with policies, can keep important people informed about company news.

  * Continuity: to provide continuity in management. Procedures, past and present, allow management to record the long-term practices of the organization. Many institutions lose valuable information when employees retire or change jobs because only they knew how to accomplish specific tasks. Writing down procedures preserves this institutional memory.

  * Education: to train new employees. Some organizations opt for procedure manuals in lieu of formal training sessions to save time and money.

### Procedures in Law

Parliamentary Procedure, or Procedural Law as it is referred to in the United States, utilizes procedures within the legal system. Procedural law is composed of the rules applied to legal proceedings. These procedures are important because they promote "fair and consistent application of due process" to all legal cases (Procedural law).

Procedures help ensure a fair, consistent, and legal handling of cases and evidence. For example, police departments follow procedures for different types of eyewitness identification (Bergman and Berman-Barrett 93).

  * _Lineups_ : They are usually conducted after an arrest is made to ensure the witness can correctly identify the culprit.
  * _Showups_ : A single suspect is viewed by the witness at the crime scene or police station.
  * _Photo Identification_ : Witnesses view photographs during this procedure to confirm a suspect's identity.

Courts also follow procedures during trials. Every process, from selecting the judge and jury to sentencing, is outlined by procedures. These procedures, developed over centuries, ensure that all states and the federal government provide a uniform legal experience (Bergman and Berman-Barrett 428).

### Procedures in Computer Science

Procedures, or sub-routines, are a main component in the field of computer science. They are part of a code in a computer program that performs a specific task. Some advantages of using procedures in computer science include

  * Breaking programs down into simpler tasks

  * Reducing duplicate codes

  * Reusing codes in multiple programs

  * Dividing large tasks among several programmers or stages of a project ("Subroutine")

### Other Uses of Procedures

Standard (Standing) Operating Procedures (SOPs) are frequently used in the fields of healthcare, aviation, education, manufacturing, and the military. An SOP "is specifically designed to describe and guide multiple iterations of the same procedure over a broad number of locations, on multiple occasions, and over an open period of time until such SOP is updated for whatever reason, or discontinued" ("Procedures"). The purpose of SOPs, as with all procedures, is to help people complete a task correctly every time. They are often official government documents, so working copies are often stamped with an official seal or contain official signatures. The original will be kept in a secure place. Some important types of SOPs are

  * Procedures for operating instruments, apparatus, and other equipment

  * Methodic SOPs which describe a testing system or investigative method

  * Procedures for receiving and inputting samples

  * SOPs for dealing with complaints

SOPs are an essential component of any large system that must run efficiently at a high level (van Reeuwijk). Figure 6.2 shows New York City's Department of Education standard operating procedures for obtaining informed consent from parents.

Figure 6.2: SOP for Obtaining Informed Consent

## How to Do I Write Procedures?

### Analyze the Audience

The first step in writing any document is defining the audience. If you define your audience correctly, you will be better equipped at providing the appropriate information. Once you determine who your audience will be, other factors must be taken into account:

  * Reading level of the audience.

  * Terminology appropriate for the audience.

  * Audience's level of awareness of the subject matter.

  * The context in which the audience will perform the procedure, including the physical location, frequency, and urgency of the procedure.

If the issue of addressing various audiences arises, a decision will need to be made regarding whether separate manuals will need to be created for each audience. Avoid combining different audiences in a single manual if possible, as this will increase the size of the manual and printing costs. Also, the larger and more cumbersome the manual, the less likely it will be used.

Some ways you can learn about your audience include

  * Talk to the people who do the work and the people who manage the work.

  * Hold a focus group to discuss the purpose, objectives, and content of the procedure manual.

  * Use a questionnaire in order to get responses from a large number of people.

  * Watch users complete the procedure to see where they encounter difficulties or use strategies the organization may not know about.

It is also important to understand how and where the procedure manual will be used. For example, if the manual needs to be available in the field, it should be a compact and easy to carry hardcopy. However, if the user spends more time at a desk with a computer, the procedure manual may be better accessed online.

### Gather Information

The information you gather — such as biases toward the product or process, issues with the product or previously unanswered questions — is just as important as determining the audience. The information you gather can come from other documents, experts, personal knowledge, or experience.

You may draw ideas for the procedure manual from

  * Previous procedure manuals

  * Specific instructions from vendors

  * Training materials

  * Government publications

  * Regulations

  * Complaint logs

As with all research, the Internet has become a vital part of preparing any procedure document. Other organizations may have manuals online from which ideas may be gleaned. If you use information from another company, seek permission first and cite the source in the acknowledgements section of the manual.

One of the most effective ways to obtain information is to talk with people one-on-one. Interviewing skills are important for a technical communicator. In order to obtain the most useful information, the correct questions need to be asked. Subject Matter Experts (SMEs) and users are often the best sources of information. SMEs are important because they are most familiar with the topic. The user is equally important because he/she will ultimately be the one using the manual.

However, understanding the task should not rest solely on the shoulders of the experts and users. As the writer, you should be familiar with the information as well. You should shadow the SME as they complete the task. Write down each step as it happens. Completing the task yourself also helps you understand the procedure and write it more completely and clearly.

### Write

Once you have analyzed the audience and gathered the necessary information, you are ready to write the procedures. Each step in writing procedures is equally important, so pay close attention to each one.

#### Step One: Explain Purpose

Explain the purpose of the procedure that readers know who should use it and the situations or tasks that it covers.

#### Step Two: List Tools

The procedure should begin with a list of tools, supplies, and equipment needed for the task. Some procedures must also define technical or legal terms.

#### Step Three: Write the Steps for Completion

Write the procedure from start to finish. Add special instructions for problems and exceptions that may occur. The reader should be able to follow written procedures step-by-step in chronological/numerical order. If the reader has to go back and forth through the sequence of steps, then the procedures have been poorly written. Figure 6.3 shows the seven-step procedure for applying for a U.S. Passport. On the website that features the procedure, each step includes a hyperlink that provides more information about completing that step.

Figure 6.3: Procedure for Applying for a U.S. Passport

Use correct terminology. The terminology used should be consistent and accessible to the audience. Define or elaborate unclear terms when necessary. For instance, Figure 6.4 shows a procedure that explains what documents passport offices count as evidence of U.S. citizenship. Avoid unnecessary jargon that may confuse the reader. In some circumstances, a misunderstood procedure can result in damaged equipment, injury, or death. Positive language should be utilized in procedures to prevent readers from interpreting or mentally rephrasing statements. For example, the phrase _Do not leave the lights on at night_ requires the reader to rephrase the phrase into the command, or procedure, _Turn the lights off when you leave_. Also, a procedure that contains the word _if_ frequently may be too complex and should be separated into simpler tasks (Cubberley 42).

Figure 6.4: Procedure Defining Documents that Establish U.S. Citizenship

Start steps with action verbs. Because procedures outline the actions that are to be taken, action verbs are most effective. Use commands and second person, rather than descriptions. Using simple, direct sentences and simple words ensures that the procedures can be understood by all users. Readers would rather be told _Locate Parts A and B_ than _As you begin, be sure you have Parts A and B in front of you_. The reader firsts needs to see the action verb that tells them what to do (Campbell 96).

Make sure that procedures are accessible to anyone who might use them. For instance, avoid procedures written solely for the right-handed. Have both a right and left-handed person review the procedures to avoid any unforeseen difficulties. In addition, make procedures accessible to users who are blind, deaf, and physically handicapped. Consult the ADA's Guidelines for Accessible Design for more information. If procedures might be conducted by users whose first language is not English, use accessible language and include appropriate visuals.

### Step Four: Add Visuals

In procedures that require the manipulation of tools or parts, such as assembling a shelf, well-placed and well-drawn visual aids can guide users as effectively as words. All visuals should include labels and be placed as closely to the relevant information as possible. Figure 6.5 shows an image from emergency procedures that informs users how to activate the fire alarm. The prominent image helps users quickly identify life-saving information in an emergency.

Figure 6.5: Image in Emergency Procedures

Headings, numbering, boldface, and boxes are also useful visuals to include in procedures. Headings and boldface can help the reader scan and skip material when appropriate. When these cues are used consistently, they can help with understanding and recall. Boxes are effective when they draw attention to cautions or warnings.

Utilize white space. White space is simply the unfilled space on the page and is of great importance. While indicating where ideas begin and end, it also gives the eyes a chance to rest. White space is a built-in organizer of information and it provides space for notes and sketches. All of these elements make procedures easier to understand and use.

### Step Five: Test, Evaluate and Revise

After writing the procedure, make sure to test it with a sample user. Have the user point out any questions, difficulties, or misinterpretations that may come up.

Use the information you received during the test portion of the process to make any revisions.

Sample Procedures

Standard Operating Procedures

Procedures or Subroutines

Classroom Procedures

Assembling a Swing Set

## For Further Reading

Page, Stephen. _Seven Steps to Better Written Policies and Procedures_. 5th Ed. Chicago: Process Improvement Publishing, 2010.

Peabody, Larry. _How to Write Policies, Procedures & Task Outlines: Sending Clear Signals in Written Directions_. 3rd Edition. Centralia, WA: Peabody Communications, 2006.

# Chapter 7: User Manuals

## What is a User Manual?

The user manual is one of the most identifiable forms of technical communication. A user manual is an instructional document with information on how to use a product, including specific details for proper usage and important safety information, if applicable. User manuals primarily contain rules, requirements, or guidelines intended to help consumers use a product properly. An effective user manual should provide users all the information they need to complete a task without burdening them with irrelevant information (Byrne).

Effective manuals should be

  * user-focused: aimed squarely at the user's needs

  * role and task focused: supportive of the task at hand

  * delivered appropriately: readily available and accessible (Byrne)

According to the Manufacturer's Guide to Developing Consumer Product Instructions, effective manuals can

  * describe the actions necessary to perform a task

  * explain how a product works and applications for which it is used

  * describe how the product may be misused

  * warn consumers about hazards through safety information

  * encourage consumers to act in a safe and appropriate way

  * meet legal obligations for duty to warn

  * meet regulatory requirements or standards for providing certain information.

## Why Do People Write User Manuals?

The user manual is an integral part of a company's product development because manuals help users get the most out of their products. The user manual is prepared by individual technical communicators or a group of technical communicators and usually distributed with the product. The technical communicator should approach writing a user manual by asking what the user wants to know. User manuals should not simply describe the product. The user will want to know how to complete specific tasks, which is difficult to explain without creating a comprehensive breakdown of the necessary steps. This comprehensive information can be overwhelming and contributes to the bad reputation of user manuals. Therefore, effective user manuals should include just enough information to answer users' questions and get them back to successfully using the product.

User manuals should answer the user's questions. The user manual is intended to be the first place to go for answers — unfortunately, that is not always the case. In order to cut back on other forms of help such as calling the company directly or finding unofficial help posted online, the user manual should serve as the first line of assistance to the customer.

## Who Reads User Manuals?

Consumers read user manuals when they encounter a problem or hope to accomplish a new or difficult task. The manual attempts to increase ease of use and decrease the number of consumer questions about the product. An easy-to-use product makes for happy customers, which creates repeat business and good product reviews to friends and family.

User manuals are an important component of a usable product, and yet consumers often resist consulting them. Consumers often complain about the difficulty of navigating manuals and express their disappointment in the level of explanation provided (Novick and Ward). Unusable documentation causes frustration and most people prefer to consult other people or the internet for help, rather than relying on user manuals. In the article, "Why Don't People Read The Manual?," David Novick and Karen Ward state that the most likely reasons readers avoid using print manuals are "their perceived unavailability, bulkiness, difficulty of navigation, inappropriate level of detail or expertise relative to the user, and being out of date, either in their content or just in the 'dated' quality of being a printed document."

In order to make manuals more attractive to users, technical communicators should work to improve the usability of manuals. Usability refers to the ease of use of a product or document, and good manuals are easy to use. A user manual needs to effectively instruct the consumer about the proper use of the product. If the manual does not accomplish this, it is worthless.

Information in manuals should be easy to find and process. In order to get the user started quickly, consider including a one-page quick start guide. Also, an index can help users locate specific information quickly.

Usability also requires that the manual fit well within the environment where users will work. For example, a car repair manual should be small and durable and lie flat so that the mechanic can read it while working underneath a car without worrying about destroying the pages with greasy fingers. In another instance, a manual for boating or fishing equipment might be laminated to protect it from water damage.

## How Do I Write A User Manual?

According to Elizabeth Slatkin's How to Write a Manual, there are four steps to writing a user manual:

  1. Plan

  2. Design

  3. Implement

  4. Evaluate

### Plan

Writing a user manual can seem like a daunting task. Creating a plan or strategy for the content in the user manual can help make the writing process more manageable. Planning helps to organize the information and ensure the manual is readable and usable. It also helps to avoid some of the problems that make manuals unhelpful.

The initial step is to find an objective. What is the purpose of this user manual? Why is this user manual necessary? Is it for a product or service? By answering these questions, a technical communicator can avoid writing an unnecessary user manual. However, a majority of the time user manuals are necessary because users need important safety information and guidance in order to use the product.

Once an objective has been established, the writer must pinpoint the audience. The audience determines almost everything about how the user manual is written, produced, and distributed. Take time to analyze the intended audience's background, skill level, needs, contexts of use, and common uses and tasks for the product. This will help to determine where to start and the kind of information to provide based on the types of questions a typical member of this audience would ask.

Finally, assess the writing requirements and constraints, including things such as a timeline and budget restrictions. Planning to write within these restrictions will ensure the user manual is successfully completed on time and under budget. Writers should also make sure to allow time for the document review and approval processes within the corporation.

### Design

Once the big picture has been thoroughly planned, writers should design the manual both conceptually and physically.

There are two stages in design:

  1. Information Design

  2. Physical Design

#### Information Design

According to the Society for Technical Communication (STC), "Information design is the detailed planning of specific information that is to be provided to a particular audience to meet specific objectives." Good information design prepares information so that people can use it efficiently and effectively.

In order to accomplish this, writers should obtain the majority of the information before the design process begins. Start with research. If the user manual is for a product, familiarize yourself with the product. Use it. Find out how and why it works. Become an expert. Second, interview Subject Matter Experts (SME). SMEs are people who have extensive knowledge on a particular topic, in this case, the way the product functions. They can answer most questions the writer generates while exploring the product. They will also have insight into potential issues and hidden uses for the product. Generally, the technical communicator and the SME spend a lot of time together to write a good, comprehensive user manual.

Once the information has been gathered, organize the information. Identify the priorities and the secondary information. Here's where analyzing the audience comes in. The priorities should reflect the needs of the users. Do they need to know why the product is made, or do they just need to know how to turn the device on? Start by outlining objectives and information important to the audience and then fill in the details. Writers should strategically organize the information by putting the most important information first and then following the common order of operating or using the product. Sometimes this means starting the manual with the tasks necessary to get started (for instance, "setting up your new router.") Writers may also organize the manual around increasingly complex tasks or user goals.

Information design can have a huge impact on the scope of the user manual. How much will be explained? How far into the process will the user manual go? If the user manual covers how to use the product, will it also cover how to properly store the product? Will it cover how to fix the product? Will it explain how to recycle or dispose of the product properly after no longer works? Ask these questions and narrow them down to fit within the objectives.

#### Physical Design

Another form of design is the physical design of the user manual. What form will it take? Will it be a print manual or an online help system? Will it include Frequently Asked Questions (FAQs) or video tutorials? Consider the type of product the user manual is for. Does it make sense to use only a print manual or does this particular product require a more expansive approach that includes different mediums for obtaining information? Also, consider the size of the user manual. Will it be big or small? Depending on the product, the answer varies. If it's a car manual, it'll need to be small to fit inside the glove compartment. The manual will also need to fit in the packaging used to ship the product. These small details can make a huge difference in the usability of the manual.

### Implement

Once these decisions are made, it is time to write. When writing instructions, keep in mind there are three different types of manual readers:

  1. Readers who read the instructions from start to finish

  2. Readers who start from the first step

  3. Readers who skip to the task or step they hope will answer their question.

Due to the diversity of potential users, it is important to write in sequential order. This way, the user can move through the steps in a logical order. This makes for an easy reference point when skipping steps. Along those same lines, make sure to include each individual step, no matter how easy or insignificant it seems (within reason, of course. No user needs to be told to buy a computer before installing software.) Another preferred organizational method is task-based instructions. Organize the information into different tasks to allow the reader to flip directly to a desired section to find the task they hope to accomplish.

It is helpful to give a background or set a baseline for beginning the instructions, such as how the product has been used before and whether the product requires preparations before starting the directions. If some background information is given before the actual instructions, this base knowledge will set the reader up for success and prevent confusion. Provide the reader with information listing the materials and tools needed to perform the task.

It is important to assume that the reader has limited knowledge or experience with the product. User manuals are typically written at the 6th-8th grade reading level, although this may change depending on the audience. Safety warnings should be in the front of the manual and in bright, flashy colors, like red or orange, to draw the eye. Safety information should classify the severity of the danger. Government standards establish three levels of safety warnings: DANGER (an immediate hazard that could cause death or severe injury), WARNING (a potential hazard that could cause death or severe injury), and CAUTION (a potential hazard that could cause minor injury or property damage). Make sure to explain symbols and icons early on.

Instructions should be phrased as clear, concise, direct commands. Sentences should be short and to the point. Avoid abstract language and utilize concrete language. Avoid double negatives to minimize confusion. Always use a positive approach by saving words such as _never_ and _don't_ for warnings and safety information. The best instructions are very specific and measure success after each task. For example, indicate to the reader that the task is successfully complete when the light turns green. This will reassure the reader that they are following the directions correctly and can move on.

User manuals often contain a large volume of information. In order to avoid overwhelming the reader, use clear and descriptive headings. That way, if the reader is looking for a specific issue to correct, they can easily skim through the document to find the appropriate section. Make navigation easier by using color to differentiate each section. The use of visuals, colorful images, and pictures can also be helpful to draw the reader's eye to specific sections and information. Tables, charts, and bullets can be used in the same way.

Other helpful things to keep in mind:

  * Use san-serif fonts to improve readability

  * Use colors to indicate important information

  * Avoid thick blocks of text

  * Use lots of white space

  * Highlight, bold, italicize

Diagrams also help users complete tasks. Diagrams typically show pictures of the step-by-step process. Pictures are worth a thousand words and this visual aid can explain or clarify a step without a long explanation. Labeling parts and referring to the numbering or lettering in the instructions assist the reader in assembly and operation.

### Evaluate

Many writers would argue that evaluation is the most important step of writing a user manual. Check the quality of the user manual by having someone do the steps just as a real user would. Perform a usability test, which involves watching users interact with the product to assess where they encounter problems. Choose someone who would be considered part of the target audience. Going through a series of usability tests before distributing the product will allow the writer to implement important changes that make the user manual more accessible and understandable to users. It is also a good idea for the writer to keep a checklist to review the instructions. If the checklist is truly comprehensive, writers can use it to identify errors that might have been overlooked.

## Sample User Manuals

Chevy Spark 2014

Apple Manual

Garmin Manual

## For Further Reading

Tips for Writing User Manuals

# Chapter 8: Drug Package Inserts

## What Is A Prescription Drug Package Insert?

A prescription drug package insert is the documentation that accompanies prescription drugs approved by the Food and Drug Administration (FDA). It conveys additional information about a drug that a prescriber or patient might need in order to dispense or consume it appropriately. According to the FDA, every prescription drug, without exception, must include this documentation.

## Why Do People Write Prescription Drug Package Inserts?

Prescription drug package inserts provide a comprehensive master list of information intended to ensure the safest administration of the drug. A patient's age, weight, medical history, and allergies are just a few of the factors to consider when either dispensing or consuming prescription drugs. Due to their methodical design, drug inserts address all possible patient scenarios. Serious consequences can occur if a physician, for instance, were to misread the tiny print on the back of a drug vial or if a consumer were to misinterpret the brief directions listed on the back of the drug's packaging. Potentially serious medical problems can be avoided as long as individuals can confirm the proper usage of the medicine in a drug insert before taking the drug. The liability issues for a physician's misstep alone, much less the tragic circumstances of an accidental overdose, demonstrate the necessity of drug inserts.

Readers can also struggle to understand the highly technical language in drug inserts. Physicians and veterinarians have the education required to make sense of this medical jargon, but an average consumer may find the terminology at least somewhat inaccessible. The person might under- or overdose, mistaking kilograms for pounds, and few have the means of measuring out drugs in decimals. In short, there's a language barrier that only technical communicators can resolve. Without condescendingly "dumbing down" the information, they must make it accessible and readable for the average consumer. Plus, as this concerns someone's health or that of someone's child or pet, the technical communicators must also lend direct-to-consumer (DTC) drug inserts an appropriate degree of compassion.

## Who Reads Prescription Drug Package Inserts?

Physicians, veterinarians, and other scientific and medical professionals are, of course, the primary audience for prescription drug package inserts. Doctors must read drug inserts in order to familiarize themselves with drug properties, classifications, recommended dosages, contraindications, etc. Based on this information, the physician must then decide whether to prescribe the medication and, more specifically, instruct the patient on how to use it appropriately. Pharmacists also read package inserts to prepare medicines properly and answer patient questions about them.

The package insert may also be read by the patient who receives the prescription, though this patient may not read the insert carefully or fully. Furthermore, the Internet has greatly enlarged the audience for package inserts. In order to remain relevant in the digital era, pharmaceutical companies now release a virtual counterpart to nearly every print drug insert. Though most consumers will never go online to read drug inserts, some will. Americans have become increasingly responsible for their own healthcare and this trend results in more virtual drug inserts being accessed online.

## How Do I Write a Prescription Drug Package Insert?

The content and layout of prescription drug package inserts, such as the number of sections and section titles, will vary to some degree from one manufacturer to another. Still, most adhere to a certain basic format to satisfy the criteria set forth by the FDA. The following list includes the most common FDA-mandated features found on a drug insert, as well as detailed descriptions of their functions. These sections use bold headings to emulate most drug inserts. They are designed this way to facilitate consumer usability.

** Preface: ** The first section of a drug insert is brief in nature. The drug's brand name (in large, bold print) and generic name (smaller print in parentheses) are provided. Buprenex, for instance, may be the brand name, but buprenorphine hydrochloride is the generic name (Buprenex). Below the names are the methods of administration such as injectable, drops, tablets, intravenous injection. The last two elements of this section are usage and dispensing restrictions. For example, certain drugs are intended for oral use in dogs or cats only, and others, in abidance with federal law, must be "use[d] by or on the order of a licensed veterinarian" (Clavamox).

** Description: ** The chemical nature and structure of the drug are presented here. This section usually classifies the medication first. Onsior, the drug insert might point out, is both a non-steroidal, anti-inflammatory drug (NSAID) and a member of the coxib class (Onsior). The remainder of the information includes molecular weight, empirical formula, chemical name, and even a small graphic depicting the drug's chemical structure.

** Clinical Pharmacology: ** This section, depending on the manufacturer's preferences, may be further divided into two subsections: Pharmacokinetics and Pharmacodynamics. "Pharmacokinetics (PK) may be simply defined as what the body does to the drug, as opposed to pharmacodynamics (PD) which may be defined as what the drug does to the body" (Benet 199). More specifically, PK involves the absorption, distribution, metabolism (or biotransformation), and excretion of the drug. PD, on the other hand, focuses on the biochemical and physiological effects that the medication has on the body, typically by either stimulating or depressing some activity (Benet 199). The results of relevant clinical trials might also be presented, including the populations who were tested.

** Microbiology and Susceptibility Test: ** Applicable _only_ to antibiotics and probiotics, this section lists the various bacteria susceptible to the medication and the details regarding the susceptibility testing, which measures "the growth response of an isolated organism to a particular drug or drugs" (UPenn).

** Indications: ** This section lists any and all of the FDA-approved uses for the drug. For example, antiemetics are indicated for the treatment of vomiting, antibiotics for infections, analgesics for pain.

** Contraindications: ** These are scenarios that prohibit a patient from using a drug safely. For instance, Clavamox is contraindicated for animals with any allergies to penicillin or cephalosporin, as they could induce a potentially fatal anaphylactic reaction (Clavamox).

** Warnings: ** These are the side effects of the drug, such as vomiting, diarrhea, inappetence, depression, restlessness.

** Precautions: ** This section covers certain physical impairments and/or drug interactions that might cause problems. The efficacy of a medication, for instance, might be intensified beyond safe levels by the consumption of alcoholic beverages; therefore, such activity is strongly discouraged. Also, a patient's reproductive status and the drug's compatibility with any additional medications that will be ingested are very serious considerations.

**Adverse Reactions:** One will locate a comprehensive list of _ALL_ possible side effects observed during clinical trials. This section should not be confused with _Warnings_ above, which singles out only the most dangerous side effects. This all-inclusive catalog of symptoms will run the gamut from mild in-coordination to death.

** Drug Abuse and Dependence: ** This section covers the dangers of prolonged use of a drug due to its ability to cause physical and/or psychic dependence. Buprenex, for example, should be prescribed with caution to patients with histories of drug abuse due to its opioid (narcotic) properties (Buprenex).

** Overdosage: ** This section presents the clinical signs that indicate an overdose and how that overdose should be addressed medically. Opiate overdose, for instance, results in potentially fatal respiratory depression, so administering oxygen, Doxapram, and assisted or controlled ventilation are keys to resolving such an episode (Buprenex).

** Dosage and Administration: ** This section lists the recommended dosages for specific body weights (in either pounds or kilograms).

** How Supplied: ** The physical characteristics of the drug are outlined here: color, shape, markings, etc. Cerenia tablets, the drug insert might state, are "marked with 'MPT' and the tablet strength on one side and the Pfizer logo on the other" (Cerenia). Storage guidelines might also be presented in this section. Clavamox drops, for example, may be stored at room temperature prior to reconstitution, but after fourteen milliliters of water have been added, the oral suspension must be refrigerated, shaken well, and discarded after ten days (Cerenia).

It is worth mentioning that some prescription drug package inserts have two sides: one specifically intended for healthcare professionals and another for ordinary consumers, the DTC counterpart. The healthcare professional side, much like the drug insert template presented above, is filled with scientific jargon. There are highly technical concepts such as pharmacokinetics, pharmacodynamics, chemical names, empirical formulae, even a graphic to illustrate a drug's chemical structure. The consumer side, on the other hand, is less technical and more compassionate. The drug Onsior, for instance, has such a two-sided drug insert: one for veterinarians and the other for cat owners. Rather than being issued a cold, sterile "Contraindications" section, the cat owner is asked, "What cats should not take Onsior tablets?" And the emotionally detached, cryptic language of the "Over-dosage" block might actually compound a consumer's panic in a crisis. Thus, the cat owner is instead comforted with "What can I do in case my cat eats more than the prescribed amount of Onsior tablets?" (Onsior). The DTC information must accommodate the consumer's state of mind.

## Sample Prescription Drug Inserts

 Drug insert for Lipitor

 Drug insert for Viagra

 Drug insert for Xanax

 DTC drug insert for Cialis

## For Further Reading

 Regarding pharmaceutical companies and the future of medicine

 Regarding FDA regulations for drug inserts

 Regarding the new FDA rules for drug inserts

# Chapter 9: Flyers

## What is a Flyer?

A flyer is an advertisement or informational sheet for an event, business, or cause. Usually, a flyer is a single sheet comprised of artwork such as images and graphics, text, or some combination of the two. Though this book uses the spelling "flyer," the term can also be spelled "flier."

Flyers should be designed to attract immediate attention. They often face competition from other flyers posted alongside them, and they are usually posted in spaces where people pass by quickly, such as hallways or sidewalks. Therefore, the flyer may have only a few seconds to grab potential readers. Flyers must be visually appealing to catch a reader's attention. Effective layout, word usage, images, graphics, fonts, and content all contribute to a flyer's visual appeal. A good layout keeps the flyer organized and makes it easy to comprehend. A few striking images or graphics grab the reader's attention. Visually appealing and readable fonts make the text come alive. Concise, clear content is a must.

## Why Do People Write Flyers?

People create flyers in order to advertise or promote an event, service, or cause, usually one that occurs at a particular time, day, or place. They are usually an inexpensive form of advertisement and can be handed out or posted to reach a large audience.

Flyers have been around for many years and have been used in various ways for a variety of reasons. "Fliers figured significantly at the time of the Reformation in Western Europe, during the American Revolution, and in subsequent national campaigns to end slavery and gain women's rights. In wartime, pilots have dropped flyers over civilian populations to persuade them not to oppose the invading armies" (Whitaker 324).

Today, people use flyers for promoting things such as music events, business openings, sales, and political causes. Many businesses use flyers to advertise their sales and inform people of the available items. In the political arena, flyers are often distributed during election years by campaigning candidates, highlighting their strengths and showing a picture of the candidate looking his or her best.

## Who Reads Flyers?

Virtually anyone could be a potential target audience for a flyer. Flyers are handed out in large crowds or posted on bulletin boards or telephone poles where a large number of people are likely to see them. A flyer is designed to advertise to a target audience; however, there is always a chance that the flyer will reach more than just the target audience or miss its target audience entirely. Consider posting flyers in an area that the target audience will likely frequent. For instance, flyers advertising a dog-friendly 5k could be posted at both pet and running stores.

## How Do I Write a Flyer?

Flyers must catch an audience's attention quickly, so visual appeal is critical. The audience will first see the prominent elements of the flyer from a distance and then move closer if they choose to read it. Even when they do move closer, audience members will want only the most essential information about the event. For instance, the flyer in Figure 9.1 below features a large image of several dogs, letting dog lovers know the flyer relates to them. The essential information about the dog pawty is clearly and concisely included in smaller font so that interested readers can find it quickly. Readers are unlikely to remember complicated information, such as lengthy street addresses or web URLs (though some flyers include QR codes that allow readers to go straight to a mobile website using their phones).

Figure 9.1: Dog Pawty Flyer

Because of the quick attention span of audiences, writers should carefully consider aspects of the flyer such as layout, word usage, images, graphics, fonts, and content.

### Layout

People will have a difficult time determining a flyer's message if they cannot find the important information or determine its purpose. A good layout can draw readers to a flyer and help them make sense of it. A flyer's layout should be organized around a clear theme or style that conveys the character or nature of the event, service, or cause. For instance, a flyer for a heavy metal concert will look very different than one for a pie eating contest. The most important information and most attractive visuals should be the largest and easiest to see from far away. The flyer's layout should draw the reader's eye in and guide it to information they need. For instance, Figure 9.2 shows a pie-eating contest flyer that uses the horns of the featured pie eater to highlight the date of the event.

Figure 9.2: Pie Eating Contest Flyer

### Word Usage

As the old saying goes, "choose your words carefully." This applies particularly to flyers, which face a small time window for communication. It is important to communicate in as few words as possible; however, meaning should not be sacrificed to keep the number of words down. Always make sure to convey the meaning clearly and completely. But if one or two words can be used instead of three or four without losing any meaning, then using fewer words is better.

The level of vocabulary used on the flyer also matters. Decisions about word choice normally comes down to using vocabulary most familiar to the target audience. Use words and terms that the audience knows well and associates with the flyer's topic. For instance, the vocabulary used on a flyer geared towards professional engineers would be noticeably different than the vocabulary on a flyer used to attract college freshmen.

### Images and Graphics

Images and graphics are a key part of visual appeal. They need to draw attention and make people take notice. Readers are often attracted to images containing faces or striking colors. Generally, it is better to use a picture that is close up on person, place, or thing instead one that is far away. An individual person is often more visually engaging than a large crowd. Also, one large image often draws more attention than several small images.

It is also important to choose relevant images that complement the flyer's topic. If an image is interesting or attractive but is not relevant to the flyer's topic, readers will be confused. They could potentially spend more time trying to make sense of the image rather than actually reading the flyer. Even worse, the target audience may ignore the flyer altogether.

### Fonts

Flyer designers should consider font choices carefully. This section presents information about font type, emphasis, color, and size.

**Typeface:** The type of text used (Times New Roman, Arial, Calibri, etc.) can make a difference in the reader's reception of the flyer. While a visually appealing type is always desirable, the readability of the type has to be the first priority. The type can be very distinctive and draw attention, but people must also to be able to read it. Flyers should feature type that relates to their topics. Sans serif fonts (without feet, or serifs, on the bottoms of some letters) are considered more technical, while serif fonts are considered more artistic. Flyer creators should also avoid mixing too many font types on one flyer. Few flyers need more than three different font types. Designers should also avoid using novelty fonts that look like handwriting because they can be difficult to read.

**Emphasis:** Emphasis refers to **Bold** , _Italics_ , and Underline. Emphasis helps certain pieces of information stand out, as many people associate bold, italics, and underline with importance. Emphasis should be applied sparingly to make sure readers do not get overwhelmed. Flyer creators can also use different font sizes and types to emphasize important information.

**Color:** The use of color is another way to modify the font. Color can be visually appealing, giving the text another dimension and making it stand out. That being said, designers can overuse colors. Colors can also make flyers much more expensive to print.

Font colors should complement one another, as well as the images on the flyer. Good designers often use colors from images, such as the dark green from a tree, as a font color as well. Font colors should also be legible over the flyer's background color. The font color should also correspond to the topic of the flyer. For instance, when creating a flyer for a football team, do not use the opposing team's colors. Use either the home team's colors or just the standard black. While the standard black is plain, it is better to be neutral than gaudy or offensive.

**Size** : Deciding on font size can be tricky, as it is very easy to make the font too big or too small. Flyer creators should factor in both the readability of the font and its proportion relative to the images.

The text needs to be big enough for people to read. While some of the text may need to be small in order to get all the necessary information in, it is best to avoid making the text so small that people stand very close to read it. The major points of the flyer need to appear in a fairly large font. This ensures that the important information stands out to the reader and increases the chances of the information being noticed. For instance, the flyer in Figure 9.3 contains a lot of text, but the most important information - the type of event - is featured very clearly in large type.

Figure 9.3: Debate Watch Flyer

The size of the font needs to be proportionate to the images used. If the images are the main attraction, then the font may need to be a bit smaller than the images to make the images stand out. Conversely, if the text matters most, then the text needs to be larger. If both are too big, the flyer will look too crowded.

### Content

People read flyers for the content, and they tend to read quickly. The flyer does not have long to grab the reader's attention and must keep that attention long enough to explain everything pertinent about the subject. This makes the conciseness and clarity of the content very important.

**Conciseness** : Flyers should use very few words to make their point. Writers should avoid lengthy, wordy, and complex sentences in favor of short, effective sentences. Edit text so that the fewest words convey the maximum meaning. For instance, the flyer in Figure 9.4 uses very few words to inform readers about the event.

Figure 9.4: Diary of a Madman Flyer

**Clarity** : Flyers should clearly convey their point to the audience. The audience should be able to look at the flyer and immediately understand it. The flyer will only hold the audience's attention for so long; therefore, the flyer's content has to be concise and clear and its layout must attract attention quickly.

## Sample Flyers

Paintball and Pizza

Dog Park Flyer

Debate Flyer

Pirate Day Flyer

For Further Reading

8 Ways to Create Effective Flyers

Visual Design Basics

#  Chapter 10: Resume and Cover Letter

What is a Resume?

A resume is a formal document that provides information about an applicant's qualifications for a specific job. It is generally one page in length, though some resumes are longer, especially when sent or posted online. It contains the information employers will find most relevant, and it is often specially catered to each position the applicant is seeking. The resume is the most important document many people ever write. The Purdue Online Writing Lab (OWL) says "Research has shown that it takes an average of ten (10) interviews to receive one (1) job offer, so your resume needs to be persuasive and perfect. Given this, your resume must be user-centered and persuasive" (OWL).

Why Do People Write Resumes?

People write resumes in order to find employment and internship opportunities.

A resume provides a potential employer with the fundamental information needed to determine whether or not to schedule an interview. Resumes are written very directly to each specific employer. They are much more effective when written this way because the employer can see that the applicants have done their homework on both the position and the company.

Who Reads Resumes?

The potential employer reads resumes. Reading a resume allows the potential employer to match the applicant's skills with specific job qualifications. Resumes are often read by HR personnel, recruiters, and hiring managers, who often sift through hundreds or even thousands of resumes for just one position. This huge volume of resumes means that each one is read very quickly; a recent study from The Ladders.com found that recruiters spend an average of about six seconds reading a resume on their first pass. Many resumes never get a second pass. Resume readers are often tired, overworked, and distracted, and they care about filling a position for the company more than they care about the individual resume writer. Seasoned resume reader Douglas Richardson writes "My job description doesn't include extending charity to job seekers and resume writers. On the contrary, I find I approach every resume with a certain impatient cynicism." Resume readers have little patience for frustrating, disorganized, boastful, or irrelevant resumes.

Increasingly, resumes are also initially read by computers, which scan each resume and match its content to keywords in the job ad. Resumes that do not survive the scan will never get reviewed by a human reader.

How Do I Write a Resume?

Writers often start the resume-writing process by brainstorming a list of all their qualifications and experiences. This list then forms the basis for the material that makes up the resume. Other writers start with the ad for the job they want and then list all their qualifications and credentials relevant to that ad.

Writers should tailor their resume specifically to a job and company. Instead of sending a generic resume out to every company, the writer can make small changes to tailor each resume to the specific position. These changes might include using buzzwords from each specific job ad or listing skills and experience most relevant to each company.

The resume must also honestly and accurately represent the applicant's accomplishments. Candidates should only list jobs they have actually held and duties they performed regularly on the job. Languages and software programs should only be listed if the applicant can use them proficiently on the job.

A resume is divided into different sections. The standard headings usually include a breakdown format of Objective, Experience, Education, and References. Resumes are customizable. With selected headings the applicant can choose the information they would like to display. Careful selection of headings allows applicants to personalize their resume to the job they seek. Other possible headings include Profile, Skills, Interests, Honors, Achievements, and Volunteer Experience. The applicants should also be specific when elaborating on the tasks they have previously performed. In addition, writers should use the active voice in their resume in order to keep the potential employer engaged.

As mentioned above, many companies use computer systems to evaluate resumes; therefore, applicants should consider using buzzwords in their resume. These buzzwords are found within the job description or function section of the posting. For instance, a job description might ask for an employee "skilled in multitasking and working in team environments." Therefore, a resume in response to the position should include references to multitasking and team work. An applicant might write "Balanced multiple accounts as part of a ten-person sales team." Buzzwords should be incorporated naturally to let the employer know that the applicant has researched the position and has the necessary qualifications. Buzzwords can help a resume survive the initial screening process.

Objective and Profile Headings

By evaluating the job posting, applicants can determine whether an Objective section or Profile section best suits their needs. They may want to use an Objective if the posting is direct and a Profile if the posting yields more room for creativity. Some applicants also choose to forgo either of these sections and lead with experience or education.

The Objective section should be no more than two sentences that clearly state what position the applicant wants and how they will represent the company if selected for the position. The objective should stress how the applicant can meet the employer's needs. Good objective statements are short and direct. An objective statement might read "Technical communicator seeking editing position that requires XML and single-sourcing experience."

If the applicant chooses to include a Profile section instead of an Objective section, it should be no more than four sentences (or a small paragraph) that clearly state what position the applicant is interested in, their current work/education in the field, and/or why they are interested in joining the field. It should also emphasize how the applicant will represent the company and offer a brief skill set to validate that promise. This section allows the applicant to speak in a professional but personal voice, thus lending it some narrative quality.

Experience, Education, and Skills Headings

The Experience section generally lists either the past 3-5 job positions the applicant has held or the three-five most relevant, in reverse chronological order, beginning with their current or most recent job. This section should list the applicant's job title, company name and location, and dates employed. Below that information, applicants should list relevant and significant job duties. Duties can be listed with bullet points or commas to separate tasks. The applicant should refer to 3-5 specific tasks previously performed, starting with the tasks that required the most responsibility. Tasks most relevant to the job should also be listed with buzzwords incorporated throughout.

Job duties and tasks make more of an impression when they are quantified. Instead of writing "answered phones," write something like "answered 300 calls daily on a 10-line phone system." Instead of writing "gathered sales leads," write "generated 35 new sales leads, resulting in a 15% increase in quarterly profits." (Make sure that your specific details do not reveal proprietary information that the company keeps confidential.) Even if the applicant does not have much experience in the workforce, he or she can still tailor past job performances to meet the needs of the potential employer by elaborating on applicable key strengths and transferrable skills. For instance, if an engineering job requires multitasking, the applicant can discuss past work that required juggling multiple duties at a restaurant.

The Education section lists relevant education and degrees. If the applicant has a degree or is currently pursuing one, that information should be included, along with the academic institution, its location, and the dates attended. Some applicants may also choose to provide a short list of courses relevant to the job. Listing a GPA is optional, especially if a candidate has been out of school for some time. If the applicant does not have a degree, they should list the above information in reference to their high school diploma or GED information. If a formal education has not been attained, this section may be omitted completely. Certifications are part of educational background and should be listed in this section as well. An additional Certifications section can encompass an extensive number of certifications.

The Skills section lists the skill sets that the applicant holds. If a Skills section is included, the information listed should be thorough and factual. Relevant skills could include soft skills, office duties, computer and program knowledge, and foreign language proficiency. The skills section is ideal for the highly advanced professional as well as the candidate with no job experience, as it speaks to the qualities that meet the needs of the employer.

Interests, Honors, Achievements, and Volunteer Experience Headings

The Interests, Honors, Achievements, and Volunteer Experience sections primarily operate to provide character information. The Interests section should provide a clear picture of the applicant's activities outside of college or workforce environments. However, the applicant should avoid going overboard with interests or listing interests that might bias potential employers. Concerning honors or achievements, applicants should include any awards that demonstrate their previous collegiate or professional character. These honors or achievements may include membership in a collegiate or professional organization and community awards or professional awards. Volunteer experience shows that the applicant is committed to the community; volunteer experiences can sometimes showcase relevant skills as well. Anything deemed a relevant or professional success should be listed in one of these sections.

References Heading

Resumes often state that references are available upon request instead of providing full contact information on the resume. Some applicants include a separate references sheet. Relatively inexperienced applicants may have the space to include reference information. References usually include approximately three people who can speak about the applicant's collegiate performance, job capabilities, or personal character. It is considered more professional to have references who can attest to work performance, but novice applicants can include a personal reference who is not a family member. The people selected as references will represent the applicant; therefore, applicants should consider their references carefully. The Reference section is optional.

Sample Resumes

Sample Resumes from The Career Center at Illinois

Sample Resumes by Industry

For Further Reading

The Purdue OWL

Matching Resume to Job Description

Resumes Content Advice

What is a Cover Letter?

A cover letter provides introductory information to a potential employer about an applicant's specific qualifications. As a supplement to a resume, a cover letter explains an applicant's interest in the position and provides additional information, such as specific skills that link the applicant to the job posting. A cover letter is formatted as a combination of a personal statement and business letter that presents the applicant's relevant experience, skills, and background.

It is imperative for the applicant to present accurate information and show the hiring company how it can benefit from the applicant's expertise. Applicants should acknowledge who they are, describe their personal skill sets, show practical application of skills through previous accomplishments, and emphasize what has led them to the prospective employer. Cover letters do more than introduce a resume, though. Great cover letters establish a relationship between the applicant and the potential employer, provide specific details that cannot fit into the resume, and showcase the applicant's communication skills.

Why Do People Write Cover Letters?

Job applicants write cover letters to introduce themselves to potential employers in a personal yet professional manner. Writers use cover letters to elaborate on their experiences, skills, and qualifications beyond the limited space provided by the resume.

Who Reads Cover Letters?

The potential employer reads covers letters. Readers can include recruiters, human resource workers, individual hiring managers, or company managers. Many potential employers read cover letters to get additional insight into an applicant's skills, experience, and personality. The cover letter is the applicant's initial contact with a prospective employer and is therefore seen as a representation of how they will present themselves within a business environment. Some employers read cover letters before resumes, but most probably read them after resumes because resumes provide information more efficiently. Not all employers want cover letters along with resumes; however, it is probably better to err on the side of including a letter that will not get read instead of omitting one that a potential employer might want.

How do I Write a Cover Letter?

Cover letters can be customized for both individual applicants and specific companies. Writers should research the company and read the job posting several times. This will allow custom tailoring of the letter to a specific audience. Letter writers can include specific references to company products, missions, values, or services that relate to the applicant's strengths or interests by writing something like "In my work at Spacely Sprockets, I learned all of the specifications for Cogswell Cog's new Excelsior product line" or "Because of my work with Habit for Humanity, I admire Luthorcorp's support of that organization." Use the active voice when writing a cover letter because it emphasizes the actions of the writer.

The section below offers a step-by-step process for creating a cover letter content.

Cover Letter Content

The letter should include a Header with the sender and receivers' contact information. This header should start with the applicant's name and contact information, followed by the date, and then the person being addressed (along with their contact information and company name and address). The letter salutation should refer directly to the person in the header; try hard to find an actual name to address the letter to. If that is not possible, "Dear Hiring Professional" is a good alternative. Avoid "To Whom it May Concern," which seems lazy and impersonal.

The Introduction paragraph allows the applicant to state the position they have interest in, how they heard of the position, and why they would make a good candidate. In this introduction, applicants should emphasize two or three important qualifications that relate to the job posting. These qualifications should provide structure to the letter and be referenced consistently throughout the document.

The Skills section should elaborate on the applicant's most important qualities and skills that they wish for an employer to consider. Ideally, these skills will be the same ones listed in the Introduction paragraph. The skills section describes these skills in detail, shows the applicant applying them in employment, educational, and volunteer positions, and explains how they can help the potential employer. The skills section generally ranges in length from one to three paragraphs. Applicants can also combine this section with the Previous/Current Jobs section.

The Previous/Current Education paragraph should include the applicant's highest level of academic achievement and how it applies towards the job position they seek. Applicants may also discuss courses, substantial projects, internships, or research opportunities from their education that relate to the position. If education is not relevant, this paragraph may be omitted.

The Previous/Current Jobs paragraph or section should reference the applicant's relevant job experiences. This section should describe how the applicant has demonstrated their qualifications through past and current positions. These qualifications should match those mentioned in the Introduction and Skills paragraphs. Applicants should use this section to show themselves in action on the job, mentioning times they have solved problems, been successful, or improved the company. Writers should list specific duties and achievements as evidence of their qualifications. For instance, instead of writing "I worked very hard during my five years at Dunder Mifflin," a writer might say "During my five years at Dunder Mifflin, I logged more hours and generated more contacts than any other employee at the Scranton branch." Similarly, instead of just writing "I am very experienced with billing processes," an applicant might write "At Wayne Enterprises, I trained seven employees to operate our billing system." Typically, the Previous/Current job section needs only one paragraph, though applicants with extensive relevant experience can include two. This paragraph might be combined with the Skills paragraph so that writers can demonstrate their skills through concrete job experiences.

The Conclusion paragraph should reiterate the applicant's interest in the position. The applicant's contact information should then be listed, as well as a request for an interview or a notice that the applicant will follow up soon. Applicants should always thank potential employers for their time and consideration.

Sample Cover Letters

Cover letters: types and samples

Cover Letter samples from Vanderbilt

For Further Reading

The Ladder Cover Letter Test

OWL Cover Letter Tips

Chapter 11: Memos

What is a Memo?

Memos are widely used in the professional world within fields such as business, government, and engineering. A memo, short for memorandum, communicates information to internal audiences. Memos and letters serve similar purposes, but include some differences, such as the formatting and where they are circulated. Specifically, memos function internally, within a company, while letters function externally, beyond the organization.

Most memos are relatively short, but there is no required minimum or maximum number of pages. For the memo to be effective, it is important that the writer includes enough information to make his or her point clear to the audience. A memo's effectiveness depends on how well the information is presented, organized, supported, and received. An effective memo should leave the audience with little to no questions about what they just read.

Memos are formatted similarly to emails, but memos are often considered more formal and official. Emails typically convey information informally, whereas memos can be used to share information in many different workplace circumstances. Memos can also serve as official statements of company policies. Companies often archive memos carefully as well, making the information easy to find (companies are also legally required to archive emails). When it comes to sharing formal information internally, the memo format often works best.

Why Do People Write Memos?

Memos express important information in workplace, government, and academic organizations. According to the writers at the Purdue Online Writing Lab (OWL), "Memos have a twofold purpose: they bring attention to problems and they solve problems" (Perkins and Brizee). Memos can be used to remind or clarify. They also "address specific people or groups for the purpose of recording an agreement, transmitting information, making a case, or enabling action" (Dobel, Elmore and Warner).

Within the professional world, memos communicate formal messages, such as

  * Results of important decisions

  * Proposals

  * Progress reports

  * Expense reports

  * Formal inquiries

  * Refusals

  * New policies

  * Transmittals of important documents or materials

Educational memos often report

  * Technical information

  * Policies

  * Requests

  * Teacher assignments

Memos are a common medium for communicating formal information, and most professional employees will eventually have to read or write one. According to "Memoranda Writing," "...memos pervade the daily life of any public servant" (Dobel, Elmore and Warner).

Who Reads Memos?

Many working professionals will likely read or write memos. Memos perform a variety of tasks in the workplace, and employees often get inundated with them. Employees often get tired of memos and tend to ignore them unless the memo attracts readers' attention. Therefore, it is important to identify and understand the audience before attempting to write a memo. The audience determines the kind of information that should be included and how it is explained in the memo. The audience also determines how much information should go into the memo. Be sure to "ask yourself three questions when considering your audience: who are they, what do they need to know, and how should you present it to them" (Dobel, Elmore and Warner).

Memos are often used in government offices, schools, and other types of municipal organizations. Some examples of working professionals who may use, send, or receive memos include

  * Business Executives

  * Administrative Assistants

  * Human Resource Representatives

  * Information Experts

  * Physicists

  * Medical Professionals

  * Government Officials

  * Teachers

For example, a business executive or an administrative assistant may have to inform employees about a change to the company vacation policy. In that case, they would write a memo and send it out to everyone the policy affects.

Another example could be a medical lab director notifying their staff about the adoption of a new record keeping procedure for patients. The director could send out a memo to the lab staff informing them of the upcoming changes.

A third scenario for memo use might involve an employee at a software company who wants to try out a new type of technology. The technology implementation has to be approved by the people in charge, however, so the employee should develop a persuasive proposal memo advocating for the new technology and send it to decision makers.

How Do I Write a Memo?

The first step in writing a memo is to identify the audience. It is important to identify who will read the memo because it will help when deciding what information to include in the text. Organization is crucial when writing a memo because a well-organized memo will ensure effective reader comprehension. The memo should be written clearly without mistakes. "Long flowery introductions, technical jargon, casual chit-chat, or showy vocabulary all distract from a memo's essential purpose: to inform or to enable action" (Dobel, Elmore and Warner).

Memos are generally one to two pages long, not including attachments. However, memos can be longer depending on the type of information being communicated. Generally, memos contain five main parts:

  1. Header

  2. Introduction/Purpose

  3. Body

  4. Closing/Conclusion

  5. Attachments

Readers often skim memos, so include clear, bold, and informative headers to identify key sections. Sub-headers, bullets, and other visual features can help readers identify key information quickly.

Header

The memo's header is similar in structure to the header of an email. Most memo headers include some variation of these four items:

DATE: The date the memo was composed or sent

TO: The memo recipient, which could include specific people (i.e. Ms. Smith) or whole groups (i.e. Human Resources Employees)

FROM: The author/sender of the memo

SUBJECT: The topic of the memo

The subject line should sum up the memo's entire contents. It should grab the reader's attention and let them know that they need to read the memo. The subject line should be specific and straightforward, not vague and weak. If the reader cannot identify the memo's topic from the subject, the memo might get ignored. The subject line must convince the audience to continue reading.

Example of Vague Subject Line

Subject: Class

Example of a Specific Subject Line

Subject: Final Project Requirements

Unless your company has different requirements, position the header at the top of the page and align it on the far left. Single or double spacing the lines is determined by the corporate guidelines. The workplace, company, or government office may also have particular formatting specifications, so the writer should be sure to double check those. Most companies have a conventional heading that indicates an internal memo.

Introduction

The introduction clearly states the purpose of the memo. The introduction is used to summarize the contents of the memo and to state the main purpose. Unlike a letter, a memo does not include personal or detailed greetings. Instead, it gets right to the point, usually in the first sentence. A typical introductory sentence might read something like "This memo introduces Stark Industries' new summer vacation policy." The introduction may also summarize the key information, indicate the relevant audience for the information, and then preview the structure of the memo.

### Body

The body of the memo includes all of its specific details. Background information (and any other information that can bring the reader up to date about the contents of the memo) should also be included under a sub-header in this section. The length of the body varies depending on the type of information the memo holds. However, this section should be as long as necessary to include all relevant details.

Be sure to cover each point in the body in its own paragraph or subsection. It is important to use clear headings and sub-headings in the memo to separate each individual point and to make it easier to read, follow, and understand. Make sure to organize points effectively. "The main points in the body should flow logically from one another and should include appropriate transitions and topic sentences" (Lewis).

The body should include all details, such as updates on

  * Tasks

  * Key information

  * Details

  * Facts

  * Analyses

  * Any other specific information

This section should attempt to answer any questions the reader may have. It should be thorough and informative. It should not omit any key details. The body can also include a requirements section, which "proposes actions or makes recommendations based on analysis provided in the body of the paper" (Lewis). However, this section is optional.

Closing Summary

The closing summarizes the entire memo and reiterates how the information relates to the reader. If the reader should take action, this section clearly outlines that action. This section should also let the reader know where to go and what to do if they have any questions or concerns regarding the contents of the memo. According to the Purdue OWL, you should "consider how the reader will benefit from the desired actions and how you can make those actions easier" (Perkins and Brizee). Unlike letters, memos do not need a signature from the sender at the end.

Attachments

Include any attachments which can be used to provide further clarity in the memo. Attachments may include charts, graphs, pictures, budgets, schedules, and any other relevant visuals or data illustrations which were not included in the body of the memo. Any attachments should be noted at the bottom of the memo.

Sample Memos

US Department of Justice Guidelines for Marijuana Enforcement

Department of Homeland Security Policy Revision

Rental Regulation Memo

City of Miami FY13-14 Budget

EPA Proposal Memo

Transmittal Memo

### For Further Reading

Writing Business Memos

Purdue OWL: Memos

References

Alred, Gerald, Brusaw, Charles, and Oliu, Walter. _Handbook of Technical Writing._ 10th ed. New York: Bedford/St. Martin's. 2012. Print.

Arrowood, Laura. Personal interview. 8 Nov. 2012.

Barry Cocklin, et al. "Team And Technology In Writing Up Research." British Educational Research Journal 5 (1998): 573. JSTOR Arts & Sciences IV. Web. 27 Nov. 2012.

Benet, Leslie Z. "Pharmacokinetics: Basic Principles and Its Use as a Tool in Drug Metabolism." Drug Metabolism and Drug Toxicity. Ed. JR Mitchell and MG Horning. New York: Raven Press, 1984. 199. Print.

Bergman, Paul, and Sara J. Berman-Barrett. Criminal Law Handbook : Know Your Rights, Survive The System. n.p.: Nolo, 2007. eBook Collection (EBSCOhost). Web. 27 Nov. 2012.

Buprenex [package insert]. Hull, England: Reckitt Benckiser Healthcare (UK) Ltd.; 2005.

Burruss, Maureen, J. Personal interview. 9 Nov. 2012.

Byrne, Ron. "The Polish Sausage Syndrome, or When All Else Fails Read The Manual." _HCi Journal of Information Development. Second Quarter (2003)._ Online.

Campbell, Nancy. Writing Effective Policies And Procedures : A Step-By-Step Resource For Clear Communication. n.p.: American Management Association, 1998. eBook Collection (EBSCOhost). Web. 15 Nov. 2012

Catanio, Joseph T., and Teri L. Catanio. "The Effects Of Integrating On-Going Training For Technical Documentation Teams." _Journal of Technical Writing and Communication_ 40.1 (2010): 77-97. ERIC. Web. 18 Nov. 2012.

Cerenia [package insert]. New York, NY: Pfizer Animal Health; 2008.

"Clarity." Dictionary.com. Web. 20 November 2012.

Clavamox [package insert]. New York, NY: Pfizer Animal Health; 2007.

"Concise." Dictionary.com. Web. 20 November 2012.

Cookson, John. "What Are Americans Studying?" Global Public Square. CNN, 2 Nov. 2011. Web. 25 Nov. 2012.

Copeland, Matt . "The Writing Context: Writer, Subject, Purpose, Audience, and Form." KSDE Writing Homepage . N.p.. Web. 15 Nov 2012.

Cubberley, Carol W. "Write Procedures That Work." _Library Journal_ 116.15 (1991): 42-45. ERIC. Web. 15 Nov. 2012.

DeKay, Sam H. "Collaborative Writing, Document Cycling, And Gatekeeping In A Fortune 500 Company: A Case Study And Its Implications For Business Communication Instructors." Conference Papers -- Annual ABC Convention (2007): 1. Supplemental Index. Web. 20 Nov. 2012.

"Development Process." Writing Revisable Manuals: A Guidebook for Business and Government. Duncan, Kent and Associates. Web. 16 Nov 2012. .

Dobel, J. Partick, Richard Elmore, and Laurie Werner. "Memoranda Writing." Memo on Memos. University of Washington, 04 2004. Web. 4 Dec 2012.

Dobrin, David N. "What's Technical About Technical Writing?" _New Essays in Technical and Scientific Communication: Research, Theory, Practice._ Ed. Paul V. Anderson, R. John Brockmann, and Carolyn R. Miller. Farmingdale, NY: Baywood Publishing Company, 1983. 107-23. Print.

"Font." Dictionary.com. Web. 20 November 2012.

Forman, Janis. "Collaborative Business Writing: A Burkean Perspective For Future Research." _Journal of Business Communication_ 28.3 (1991): 233-257. Business Source Premier. Web. 22 Nov. 2012.

Gigante, Shelly. "How Boomers Will Impact the Health Care Industry." cnbc. cnbc online, 22 Feb. 2010. Web. 23 Nov. 2012.

Harris , John. "The Project Worksheet for Efficient Writing Management ." Trans. Array Strategies for Business and Technical Writing . Kevin J. Harty . 7th Edition . Boston : Longman , 2011. 34-43. Print.

Lauren, Andrea, M. "Conflict Management Styles And Aggressive Communication In Email: An Examination Of Organizational Interactions." (2012): OAIster. Web. 27 Nov. 2012.

Lee, Martha F., and Brad Mehlenbacher. "Technical Writer/Subject-Matter Expert Interaction: The Writer's Perspective, The Organizational Challenge." _Technical Communication_ 47.4 (2000): 544. Communication & Mass Media Complete. Web. 17 Nov. 2012.

Lewis, Kelly. "Student's Guide to Memorandum Writing." Department of Accountancy. Project Discovery Accountancy Communications Team, 21 2010. Web. 4 Dec 2012.

Mathes, J.C, and Dwight W. Steveson. "Audience Analysis: The Problem and a Solution." _Strategies for Business and Technical Writing_. 7th Edition. Kevin J. Harty. Boston: Longman, 2011. 168-183. Print.

"Medical School Admissions Statistics & Trends." Johns Hopkins University. Johns Hopkins University online, n.d. Web. 23 Nov. 2012.

Miodownik, Mark. "Is the Instruction Manual Heading For Extinction?" _The Guardian._ The Guardian, 19 Aug. 2009. Web. 3 Dec. 2012.

Novick, D., and Ward, K. (2006). "Why don't people read the manual?" _Proceedings of SIGDOC 2006_ , Myrtle Beach, SC, October 18-20, 2006, 11-18.

Onsior [package insert]. Switzerland: Novartis Animal Health; 2010.

Pease, Alison. "Pharmaceutical Companies and the Future of Medicine." _Yale Journal of Medicine and Law_. October 19, 2013.

Perkins, Courtnay, and Allen Brizee. "Memos." Purdue Online Writing Lab. Purdue University, 21 2010. Web. 23 Nov 2012. <<http://owl.english.purdue.edu/owl/resource/590/1/>>

Pfeiffer, William Sanborn and Adkins, Kaye E. _Technical Communication: A Practical Approach_. 8th ed. Upper Saddle River, NJ: Person Education. 2010. Print.

Pinelli, T.E., Barclay, R.O., and Kennedy, J.M. "Survey of Reader Preferences Concerning the Format of NASA Langley-authored Technical Reports." Publishing Research Quarterly. 13.2: (1997): 48-68.

"Procedural law." Wikipedia, The Free Encyclopedia. Web. 17 Oct. 2012.

"Procedure (term)." Wikipedia, The Free Encyclopedia. Web. 21 Sep. 2012.

Rahim, M. Afzalur. Managing Conflict In Organizations. n.p.: Quorum Books, 2001. eBook Collection (EBSCOhost). Web. 1 Dec. 2012.

Rude, Carolyn and Angela Eaton. _Technical Editing_ 5th Ed. Boston: Longman, 2011. Print.

Sageev, Pneena, and Carol J. Romanowski. "A Message from Recent Engineering Graduates in the Workplace: Results of a Survey on Technical Communication Skills." _Journal of Engineering Education_ Oct. 2001: 685-93. Print.

Salary Wizard. "Medical Writer I Salary." Salary.com. N.p., Nov. 2012. Web. 23 Nov. 2012.

Salemi, Vicki. "Technical Writing Ranks Among Top Ten Paid Virtual Jobs." Media Bistro. Media Jobs Daily, 22 Oct. 2012. Web. 2 Dec. 2012.

Sides, Charles H. _How to Write and Present Technical Information_. n.p.: Oryx Press, 1999. eBook Collection (EBSCOhost). Web. 15 Nov. 2012.

Sikula, Sr, Andrew, Sikula-Dodds, Alissa, Sikula, John. "Eleven Email Etiquettes." Supervision 73.5 (2012): 8. MasterFILE Premier. Web. 20 Nov. 2012.

Singer, J.P., G.M. Balliro, and N.D. Lerner. _Manufacturer's Guide to Developing Consumer Product Instructions._ Washington, D.C.:U.S. Consumer Product Safety Commission (CPSC), 2003. Online.

Slatkin, Elizabeth. "How To Write A User Manual." Berkeley, Calif.: Ten Speed Press, 1991.

Smith, Jacquelyn. "America's 20 Most Surprising Six-Figure Jobs." Forbes. Forbes Online, 31 Jul. 2012. Web. 2 Dec. 2012.

"Subroutine." Wikipedia, The Free Encyclopedia. Web. 20 Oct. 2012.

Sumecki, DaviD, Chipulu, Maxwell, and Ojiako Udechukwu. "Email Overload: Exploring The Moderating Role Of The Perception Of Email As A 'Business Critical' Tool." _International Journal of Information Management_ 31.(n.d.): 407-414. ScienceDirect. Web. 20 Nov. 2012.

"Technical communication." Wikipedia, The Free Encyclopedia. Web. 26 Nov. 2012.

Tobolowsky, Barbara F. "Thinking Visually: Using Visual Media In The College Classroom." _About Campus_ 12.1 (2007): 21-24. ERIC. Web. 21 Nov. 2012.

Tuffley, David. _Software User Documentation: A How To Guide for Project Staff_. CreateSpace Independent Publishing Platform, 2011. Print.

Vaczek, David. "FDA Unveils New Package Insert Format." Pharmaceutical & Medical Packaging News. N.p., 9 Feb. 2006. Web. 23 Nov. 2012.

van der Meij, Hans. "The Role and Design of Screen Images in Software Documenation." _Journal of Computer Assisted Learning_ 16 (2000): 294-306. Print.

van Reeuwijk, L.P. Netherlands . Food and Agriculture Organization of the United Nations . Guidelines for Quality Management in Soil and Plant Laboratories. Rome : National Resources Management and Environment Department , 1998. Web.

Vogel, Peter. _Read the Manual!: The Little Book on How to Write So You'll Actually Get Read_. Ontario: PV&H Information Services, 2009. Print.

Weber, Richard M., and Brian D. Horn. "Taming Your Inbox." _Journal of Financial Service Professionals_ 65.4 (2011): 33-36. Business Source Premier. Web. 22 Nov. 2012.

"What's the Difference Between Technical Communicator and Technical Writer?" Society for Technical Communication. STC, n.d. Web. 28 Aug. 2012.

Whitaker, W. Richard, Janet Ramsey, and Ronald Smith. _Media Writing: Print, Broadcast, and Public Relations_. New York: Routledge, 2009. Print.

Williams, Joseph M. _Style: Toward Clarity and Grace_. Chicago: U of Chicago P, 1990. Print.

"Writing: A Ticket to Work ... Or a Ticket Out." The National Commission on Writing for America's Families, Schools, and Colleges. CollegeBoard, Sept. 2004. Web. 25 Nov 2012.

"Writing Policies and Procedures." Copedia . Endeavor. Web. 19 Nov 2012. .

Zeleznik, Julie M. _Technical Writing : What It Is And How To Do It._ n.p.: LearningExpress, 1999. eBook Collection (EBSCOhost). Web. 1 Dec. 2012.

# Contents

  1. Front Matter
  2. Table of Contents
  3. Introduction
  4. Chapter 1: Overview of Technical Communication
  5. Chapter 2: Proposals
  6. Chapter 3: White Papers
  7. Chapter 4: News Release
  8. Chapter 5: Software Documentation
  9. Chapter 6: Procedures
  10. Chapter 7: User Manual
  11. Chapter 8: Drug Inserts
  12. Chapter 9: Flyer
  13. Chapter 10: Resumes and Cover Letters
  14. Chapter 11: Memos
  15. References

