Article Summary: Charney’s “Empiricism Is Not a Four-Letter Word”

Do empirical methods have a place in the scholarship of technical and professional writing? At the time this article was written (1996), an influential cadre of technical communication researchers had been calling into question not only the validity of these methods but also the moral and ethical character of those who used them. Basing their rejection of empirical methods on feminism and social constructionism, these scholars successfully forced quantitative research in technical communication out of the mainstream. With this article, Charney’s aim was to expose the logical fallacies of this movement, as he saw them, and to attempt to restore the reputation of quantitative methods. His hope was for a community of scholarship that valued qualitative and quantitative research methodologies in equal measure.

The Mischaracterization of Science

Although many critics of science merge objectivity, positivism, rationalism, and materialism (among other terms), Charney notes that these concepts can and should be separated and that many notable scholars have upheld some, but not all, of these ideas. Nevertheless, critics equate the quantitative approach with an ethos of self-interest and political status quo. By eliminating the richness of human experience from their research, empiricists are viewed as misrepresenting the true nature of the world as reducible and fully describable.

A key accusation against empiricism is that it is inherently sexist. Some scholars charge that empiricism reinforces masculine modes of knowledge and shuts out other, feminine, paths, such as intuitions, traditions, and personal experience. Charney counters that, contrarily, the pervasiveness of sexism in our culture has often been revealed through quantitative analyses and that empiricism has probably opened the door to many more people to join in the production of knowledge than were allowed to in cultures that privileged the elitist few. Because science is open and repeatable, it allows anyone to challenge it and add to it.

Indeterminacy

Critics also point to the fundamental contradiction in science that so-called “objective” methods are not really objective at all. In every data set, there is variance; in all methods, there are indeterminate sources of error. How, then, can scientists claim absolute objectivity? Charney concedes that “scientific knowledge and methods are, at least in part, socially constructed.” However, he says, this does not invalidate the central rationality of science. Science is a process, not a discrete, monolithic entity. Imperfect tools are used to continually improve our understanding and to create new tools that are less imperfect than their predecessors. Science is self-critical and self-examining—nothing stands that is shown to be false. To Charney, empiricism is what prevents a totalitarian ethic because it promotes a free and open exchange of ideas. This is in direct contrast to the characterization of science by the opposing side as an upholder of oppressive power structures.

What’s Really Objective about Objectivity?

As noted, critics often charge that science is not objective because its methods are socially constructed and inherently indeterminate. However, to philosophers of science, there is no contradiction between social construction and objectivity—it is largely a misperception of science that leads people to reject it. The social constructivist roots of science are evident in the way that scientific ideas and methods are tested and re-tested. No one individual holds absolute authority. Knowledge is arrived at through consensus via a community-based process. Most scientists do not see their own results as fixed, immutable truths, but rather as probabilities that lean in one direction or another. As a result, scientific articles are best viewed as rhetorical devices to disseminate results and attempt to convince one’s peers of the value of one’s work. This process results in ever-improving methods and knowledge claims. It is precisely this aspect of science, and not the “supposed neutrality or disinterestedness of individual scientists,” that defines objectivity in science.

How Researchers Treat Their Participants

Another critique of empiricism is the cold manner in which quantitative researchers approach their research participants. Critics equate distance with uncaringness, objectivity with amorality. Charney points out that “these characterizations smack of the worst kind of exclusionary identity politics” in that “they essentialize the researchers on the basis of their methods.” In contrast, many quantitative researchers care deeply for their research participants—deeply enough to remain distant and “cold.” This distance is what allows them to report accurately on what they observe, and what allows others to reproduce their studies and validate their results. The methods one uses cannot be used as a gauge of the moral character of those who use them. In that light, the supposed caring and compassionate nature of qualitative researchers cannot be ascertained purely through their own descriptions of their participants. Their reports are just as calculated as those of quantitative researchers—they must assume a particular “voice” in order to appeal to their readers (primarily, other qualitative researchers).

Objectivity Reinforces Collective Authority

Qualitative analyses are inherently situated in the place they were conducted. Studies that rely on qualitative methods are not generalizable to broader contexts, and the validity of these studies cannot be independently verified. Paradoxically, this lends absolute authority to the individual researchers because they are the only ones who can make claims about their own research. Although qualitative research is often viewed as democratizing and collectivist, the opposite is true. Quantitative research, conversely, relies on the community for its credence. And because quantitative research leads toward generalizability, the results of multiple studies build upon one another to form an interconnected web of understanding.

Toward a Synthesis of Qualitative and Quantitative Methods

Neither qualitative nor quantitative methods alone are sufficient to create a robust field of scholarship in technical communication. Both reveal knowledge in their own way, and both reveal different kinds of knowledge. Charney believes that, as a field, we should embrace all methods that have the capability of leading us to our collective goals.

Barker Chapter 6, Planning and Writing Your Documents

This chapter provides guidelines for planning a documentation project, including a production task list for each of the nine phases of the process. Barker states, “The key to producing quality documentation is to follow a process” (174). The nine phases of documentation production are to:

1. Start the project
2. Perform the user analysis
3. Design the documents
4. Plan the documentation project
5. Write the alpha draft
6. Conduct reviews and tests
7. Revise and edit
8. Write the final draft
9. Conduct a field evaluation

Each phase builds on the previous one, and implies testing and other ways to check progress.

Descriptions of the Phases

1. Start the Project

Writers should start by getting to know the computer software in question, considering how the material should be adapted to the user’s needs. Some documentation projects may be written by lone writers. But often projects are created in teams. Both development teams and writing teams work to develop software documentation. The development (“cross-functional”) team develops the entire project and usually includes professionals with varied backgrounds and skills. The team might include managers, market and system analysts, programmers, and documentation specialists. Those on the writing team focus on publications: writing, editing, or testing documents. This team might include writers, editors, graphics designers and testers.

Once the need for the software is established, project documents are developed. Project plans list the goals and justification for the project, the types of systems already in place, needed user documentation, and preliminary schedules and task assignments. Program specifications describe software details such as the programming language and operating system. Market analysis documents summarize the results of user analysis, looking at the motivations of the software purchaser, rather than the software user. The information plan describes what manuals or help will be created to accompany the software, identifying the primary users and including preliminary user analysis. The management plan specifies the resources for completing the project, including a day-by-day strategy and work roles. It also sets meeting dates, milestones, and deadlines for the project.

Online help systems, which contain information about program operations, deliver information using the WinHelp or HTML formats, or in portable document format (PDF). Topics are arranged according to user activities. Online help system development is similar to tutorial development, but differs in several ways. User analysis focuses on workplace activities and the users’ familiarity with technology and help systems. For the writer, time is required to learn the authoring system that will be used. Special codes are required to link the correct online help topics to the user “requests” for help while using the system. Links, as well as content, must be tested. In addition, testing must be performed in different operating environments, such as Windows, Macintosh, Linux, Unix, Internet, and Intranet. Testing takes much more time.

One of the biggest challenges in online help development is in choosing the best authoring environment. Some of the better known authoring environments include Doc-to-Help, Sevensteps, Microsoft HTML Help 1.3 SDK, RoboHELP, and AuthorIt. Consider authoring environments in terms of what features will be provided to the users. Management features allow project planning, scheduling, and tracking, as well as reports. It is also important to be aware of the types of help formats they can support, such as Word or PDF, Windows Help, HTML, XHTML, Microsoft HTML Help, or Java Help.

2. Perform the User Analysis
User analysis involves interviewing and observing users to identifying their user types and learning preferences, as well as activities they will perform. This helps to determine which program operations should be included in the program manuals and help documentation. User activities will guide the groupings of topics in the table of contents (as opposed to a default manual, which records the functions of the program without regard to user tasks). User analysis will also give writers a sense of how familiar users are with help systems and what kinds of features they expect to see.

3. Design the Documents
Keeping the user's needs in mind, documents are outlined and designed. Choices are made on the document forms (tutorial, procedures, and reference) as well as which products will be used (training, guided tours, tips, etc.) Throughout the process, changes will be made as you test your documents with users and reviewers. For online documentation, a list of keywords and glossary terms begins to be created, as well as creating table of contents topics.

4. Plan the Documentation Project
A documentation project includes two parts. The design plan, also known as the "content specifications," describes what the manuals will look like and what they will contain. It should include (1) a description of the users and what kinds of tasks they will want to complete, (2) a discussion of the documentation objectives, and (3) a description of the content including outlines and the layout. The project plan has to do with how the manual will be produced. It will include deadlines of drafts, tests, and reviews, different team members' responsibilities, and knowledge resources. It will be necessary to estimate how long different project tasks will take. The documentation plan should be throroughly reviewed by managers, users, and clients. If the plan is complete and understandable, another writer should be able to follow it to produce the manual as you envision it.

In online help systems, the team will contain writers/experts as well as a developer who will handle the techncial aspects of the project.

5. Write the Alpha Draft
The alpha draft is the first complete document "including all the front matter, text, graphics, appendixes, indexes, " etc. The alpha draft will be tested, reviewed and edited.

In online help systems, the process involves writing content but also "creating links and interconnected relationships among topics". A special program called a help compiler, included with help authoring programs, can test the help system to discover incomplete links, missing cross-references and other types of errors.

6. Conduct Reviews and Tests
Clients, users, and others can review the alpha draft at the same time that usability testing is being designed and conducted. Feedback received can be used in making corrections and improvements.

Testing online help systsems is usually done after the whole system is completed because of the interconnectedness of all of the parts. The content must be tested as well as insuring that all links and pop-ups perform correctly

7. Revise and Edit
Information from feedback and reviews can be incorporated into the document. In addition, an editor can verify the document for accuracy and organization.

8: Write a Final Draft
Activities done in the previous two steps will help to greatly improve the document; the end result should be a camera ready document or online help that is ready for distribution with the program.

9. Conduct a Field Evaluation
The field evaluation, done by users and operators of the program, allows you to judge how well your product fits the needs of the intended user. Information gathered will provide input for the next project.

Field evaluation of a online help system can be done using email or feedback links that allow users to provide feedback. It can also be done using an electronic survey on a website.

In addition:
There are two main kinds of projects:

• A stand alone project is one for which the writer is assigned or contracted to develop documentation for a program that has already been written. The writer can learn the entire program before having to write about it. However, they have no input into user analysis or the design of the project
• A development project is more common in organizations that create software as their main products. Processes are in place for creating both software and documentation side by side. Writers can be involved in the project from the beginning and can provide input into the usability and interface of the project. The writing usually parallels the design of the product.

There are also three typical development methodologies in creating documentation:

• The most traditional method, the waterfall method, follows user and program specifications throughout the process through a series of planned, organized steps. It is a more rigid process which doesn't allow as much flexibility if users' needs or program features change.
• The rapid-development method allows teams to brings products to market faster. This method focuses on prototypes and usability testing; users' needs can be considered and adaptations made throughout the process.
• The object-modeling method melds the two previous methods. If follows sequential development as well as incorporating usability tools, including a "use case" model, which is " a plan that tells exactly how the user will employ the program in the workplace." Programmers then focus on these tasks to create software that, when done well, will specifically fit the user's needs.

Campbell, Chapter 6: How Do I Get Them to Read This?

Making a good first impression is important in order to draw readers in. Design can accomplish this. Keep in mind two things: simplicity and visual clarity. If the document appears to be easy to read, then it probably is. A reader isn't going to spend time reading a manual that doesn't look like it will be easy to read. Keep the design and format simple.

Twenty design elements should be followed when creating a document, including elements like font, spacing, margins, and white space. (See the Design Tip Sheet 6-1, page 223 for the complete list.) These design elements are effective because of the human brain and eye movement. Because the brain can only handle up to seven different items at one time, it is good to limit your documents to three different items, to make it easier on the reader. No matter what, don't go over seven items. Use the Rule of Three as your guide in document design. Eye movement follows four patterns, which help determine effective document design:

1. Line length: Readers comprehend about 40 characters per glance, so it makes sense visually to limit line length to 40 characters.

2. Words per second: The eye comprehends three or more words per second, so keep words simple and use headings and sections to enhance the message.

3. Words at a time: The eye comprehends two or more words at a time. Because the eye groups words together, the small words may get missed, so be careful of your wording. Write as precisely as possible, cutting down on descriptive words.

4. Zigzag reading pattern: The eye reads in a zigzag pattern, from top to bottom and left to right, so be cautious about emphasis and image placement to avoid the eye from going off of its normal reading track.

Chunk

The limitations of the brain and eye require that we "chunk" material on the page to aid in visual recognition. If we present the reader with too much information at once, the reader will probably not be excited to digest it all. If we chunk it, the reader is more likely to be receptive to what we have written. There are many ways to chunk (use short words, sentences, and paragraphs; headings; color; lists), the important thing is to do it.

Add White Space

Adding white space to a document gives the impression that the material can be read easily. This is a psychological effect on the reader and will result in a more usable document. Dense text on a page creates a gray appearance and reduces the ability of the reader to get through the material quickly. Opening up the document by adding white space draws the reader in and motivates them to read.

However, adding white space will increase the overall length of your document. Usually, the need for white space trumps the desire for a shorter document. If, however, the added white space will create a document that is too massive, you have only two options:

1. cram it all into one dense manual, or
2. split the material into two manuals with more white space.

Your decision will be based on the needs of your users.

Remember that too much white space can be just as bad as too little. Create a visually appealing balance by exercising restraint, discipline, and moderation.

Be Consistent
Forget the adage that "consistency is the hobgoblin of little minds." Be consistent in all aspects of your document design and writing. Consistency will reduce the effort needed by the reader to make sense of your document. Inconsistencies break the reader's rhythm--avoid this.

Team 4 (Chapman and Lukkonen)

Chapter 5 (Barker): Analyzing Your Users

The first step in the documentation process is to gather information about users. Barker outlines eight analysis areas and begins the chapter discussing the planning required prior to user analysis.

User Analysis Preparation and Planning

Before the user analysis inquiry begins, considerable time must be spent planning. Barker identifies the following guidelines for conducting a user analysis:

• Choose users carefully. Begin by thinking about as many groups of users as possible and create a list. To choose which users to analyze ask yourself which users would most likely use the program and which users would be the most realistic group for you to interview. Start to build a list of tasks/activities users will use the program for.
  
• Study users before and after using a program. Pay attention to the tasks/activities the users perform without your program. According to Barker, “Research shows that skills learned in the workplace can transfer to skills using software.” [122] Observe the work area for “artifacts” (notes, manuals, cheat sheets) that may provide clues about user habits. Observe what values confront the users (team skills, efficiency, ethical issues, etc.) to help understand their attitudes.
  
• Research professional behaviors. If you don’t have access to actual users, create a model by research a user’s occupation through reference materials and/or company documentation.
  
• Write use cases. Your goal is to find out what motivations, behaviors, values, and attitudes exist beyond what you can immediately observe. One approach to discovering this information is to write a use case. A use case is a narrative of a user’s “normal” work pattern. An example follows: Every Monday morning, Randy retrieves the updated sales figures for a weekly 9 a.m. meeting. He must first….” The author recognizes the above process takes time but does provide a visualization of the user.
  
• Plan interviews carefully. User interviews provide the most significant user analysis feedback. Take time to carefully plan for user interviews to avoid repeat visits or unproductive interviews by reviewing software and identifying issues, writing questions, and determining scope of interview.
  
• Involve users in all phases of the project. User analysis should take place throughout the entire documentation process: writing, reviewing, and testing. Involving the users through the process assists in establishing a working relationship with them, which allows you a better opportunity to “situate his or her actions in the workplace.” [133] A focus group can also be established and used throughout the documentation process.
  
• Identify document goals. Clearly identify what you expect to do for the user: “the activities you want to support and the user performance you want to empower.” [135]
  
• Tie the user analysis to document features. Make sure to tie the user analysis to the software documentation. Jot down ideas obtained throughout the user analysis process. Finally, match document features with the results of the user analysis process.

User Analysis

The purpose of user analysis is to study the user in the context of his/her work environment to see what tasks the user performs with the software while at the same time recognizing the cultural differences between you and the user. The process of user analysis involves asking questions and determining how the answers should be applied to the design of manuals and help systems. The following items describe the questions to address throughout a user analysis.

1. Tasks and activities the user will perform. “Learn the activities associated with his or her type of work.” [142] Look for tasks unique to the user’s workplace, tasks that require more than one software program and/or information from data resources, and tasks that require communication with other people.
   
2. User’s information needs. Expand the analysis into other work activities and roles users must participate. Find out what information the user needs, origin of information used (Internet, databases, trade magazines, etc.), and how the user communicates.
   
3. User’s work motivations. Try to tap into how software is used to help satisfy work motivations. According to Barker, “what motivates users professionally will also motivate them to do well with software—to assemble interface elements and basic operations into meaningful sequences leading to an objective.” [147] Tables 5.14 identifies sources of workplace motivation, and Table 5.15 suggests how to employ the motivational information in manuals.
   
4. Level of the user’s computer experience. Users bring a wide range of computer experience to each new program and so require different levels of support.
   
   The novice computer user typically experiences anxiety with new technology and is generally distrustful of manuals. The novice user would prefer to be told what keys to press rather than self-exploration of the program.
   
   Experienced users view software as a tool and have definite preferences as to how they want to learn new skills and programs. The experienced user understand the value of manuals and use online help systems more readily.
   
   Expert users often work in the software industry, so they are confident with technology and can troubleshoot effectively. Expert users learn new programs easily but will consult a manual or online help.
   
   Table 5.16 describes each of the three types of users and generalizations about documentation preferences of each type.
   
5. User’s knowledge of the program’s subject matter. The level of knowledge a user has about the subject matter of a program will determine how much background information to supply in the program. For instance, an accountant would probably need less background information for a tax program than the first-time tax preparer.
   
6. User community. Within organizations some type of official group (who Barker labels a community) forms whose purpose is to support software issues. User analysis should “investigate two things: the user groups that your users already participate in and your user’s willingness to join groups for mutual support.” [153] Examples of user communities include help forums, special interest groups, newsgroups, user groups, and web resources.
   
7. User’s learning preference. How does your user prefer to develop expertise with the new software? Generally, a user will learn with the help of an instructor, learn with the help of a manual, or learn through the computer. Consider how computer experience will determine learning mode. For instance, a novice computer user will more than likely prefer to be taught by an instructor rather than use a manual or computer assistance.
   
8. User’s usage pattern. “Usage pattern refers to the interaction of users with programs over time.” [164] In other words, how many features does a user learn or regularly use when using new software. Three main usage patterns exist: regular, intermittent, and casual usage. Knowing the usage pattern assists in developing better manuals and help.

Hood/Carlson

Article Summary of Steven Katz’ “The Ethic of Expediency”

This article began as a conference paper and was initially published in the Journal of Business and Technical Communication in 1993. Katz begins with a citation of Cicero, which points out the power of rhetoric and the importance of ethics as well as the danger when rhetoricians lack ethical conscience.

Next, Katz uses a real-life example of what happens when a writer of a technical document lacks any ethical conscience: he prints a memo that was written in 1945 by a SS soldier to his superior. The memo holds factual information about “load” capacity and transportation. Only a reader with supporting information would be able to find out that with “load” the author is referring to Jews, homosexuals and Gypsies being transported to a Concentration Camp (CC). The memo is written in a detached, sterile and cold way, describing the inhumane transportation conditions in a way that the reader might consider “load” being wood, rocks or anything without life. Shockingly, the recipient of the memo knew exactly what the author referred to with “load”. At no point within the memo, the author has to define that word, even though it is key to the memo’s functionality.

The Final Solution: An Ethical Problem in Rhetoric

In his article, Katz begins to provide necessary background information about the memo to the reader. He further evaluates the memo as a technical document for its clarity, format, argumentation and style. Katz points out that the memo is written in a concise technical format, with a clear purpose statement and ends with a proper recommendation of how to solve the issue at hand. This clearly demonstrates a logical layout of the document. However, the problem with the memo is that the writer shows little concern that his memo’s additional purpose is to transport humans to a CC for torture and death. While the document exhibits excellence in rhetoric, it is devoid of ethos. The expediency of the document becomes more important that the ethical aspect of its purpose. Katz calls it “the ethic of expediency”. The writer of the document didn’t question the need or purpose of the document; he merely functioned as a bureaucrat, fulfilling his duty.

Katz points out that each writer needs to adopt the ethos of the organization he/she works for in order to perform well (198). This theory would then explain the development in Nazi Germany, where the entire nation adopted the ethos of Nazi bureaucracy. Katz develops his theory further by arguing that the ethics of expediency are rooted in Aristotle’s Rhetoric and Nicomachean Ethics. Katz points out that there are dangers associated with rhetoric that is grounded solely on the ethics of expediency.

Ethics in Deliberative Discourse: Expediency

Objectivity in technical writing is a requirement; however, it becomes difficult when one adds the ethical aspect to it. Katz tries to define the role of ethical decision-making in technical communication by describing the role of ethos in rhetoric. Thus, ethics becomes an important component in deliberative rhetoric. Being objective as a technical writer should not equal being devoid of any human component while creating the document. Technical writing needs to be based “on deliberative rhetoric from the standpoint of both rhetoric and ethics” (199).
The definitions of “virtue”, “moral wrong /right” and “truth” are important for technical writers. However, if “right” and “wrong” is subject to interpretation, then the term becomes subjective and no longer fits the need of objectivity in technical writing. Applying this in the most extreme case, Aristotle’s “utility is a good thing” would support the ethics of expediency and put the functionality of the document above its content (200).

Hitler’s “Ethical” Program?

Katz further examines Hitler’s writings and his philosophy and points out the basis of Hitler’s successful application of his philosophies: “For Hitler, as for Aristotle- at least in his discussion of deliberative rhetoric-there seems to be no distinction between “practical wisdom” and “moral virtue”, between expediency and the good, as long as rhetoric serves its end, that is, the State.” (202). Hitler also used science and technology as moral expedients and created a “new philosophy” for an entire nation; he was able to create a sense of urgency as well as creating “common” goals “for the sake of technology”. Efficiency, excellence and elegance in killing became a goal for all followers.

The Technological Ethos and Nazi Rhetoric

Katz tried to define the ethos of technology; becoming part of the culture, technology also “becomes both a means and an end in itself.” (204). In industrial capitalism, value is measured in terms of technical criteria, use, efficiency, speed, productivity and usefulness while social customs, values and beliefs become less and less important. This may be because ethical values cannot be measured and are difficult to define.

Katz analyzes Hitler’s means of propaganda and explains its success: Hitler used rhetoric as a technological instrument to capture the masses and use them to execute his will. Furthermore, his propaganda also becomes a means of justifying his actions. Katz points out that the major reason for writing about this topic is to understand the essential relationship between rhetoric and ethics.(206)

Expediency in Technological Capitalism: the “Final Problem” For Us

What does this article mean for us in today’s culture? In order to prevent the history from repeating itself, people need to understand the importance of ethos and the dangers of pure economic expediency and personal happiness above wellbeing of others. Katz calls scholars, teachers and writers to contribute to a better understanding of the role of ethics and its importance in technical writing. He believes that the awareness for ethical decision-making can be taught and should become a state of mind that can be then utilized within society.

Final Question for Reader from Lance and Vanda:

We want to challenge you to think about and maybe even answer this question:
Can you think of other situations where expediency took precedence over ethics? (e.g. a company would rather pay legal penalties that resulted from a particular defect rather than fixing the problem in the first place).

Thank you for reading this summary! Lance and Vanda

Campbell, Chapter 5: Is There a Certain Format I Should Use?

There is no answer for the best format for policies and procedures. It depends on a number of things.

Beginning to Determine Format
The format depends on your audience, material, and management. However, if you are writing policies and procedures for an outside licensing, accreditation, or regulatory body, you may not have a format choice.

Format and Audience: Figure out who your audience is because certain formats work better for certain audiences (i.e. flowcharts for engineers).

Format and Material: Your information should narrow your format options (i.e. safety procedures require absolute clarity, therefore, your format should be clear, distinct, and make the material easily understandable). The Format Options Chart (5-1) gives general guidelines for which formats to use with which types of material).

Format and Management: If you want a format that management is not comfortable with, make sure to explain it and present your reasons for choosing it.

Deciding on Page Layout
The page layout gives readers basic information about the policy or procedure, such as title, number, or effective date; it also identifies information that is critical to proper use. The amount and types of information you standardize in your page layout is up to you. The goal is to keep it simple so the standardized information that doesn’t detract attention from the policy or procedure itself. Readers should be able to scan the page layout quickly, and then focus immediately on the body of the text.

Choosing Among Format Options
Once you decided on page layout, you need to choose a format for the main text. You have several options: narrative, outline, playscript, or flowchart. You also have secondary format options: question and answer, troubleshooting, matrix table, and list. Once you choose a primary format, you need to use it throughout your document.

Using Primary Formats
The following are brief descriptions of primary formats, which are the mainstay of the document.

Narrative: standard sentence-and-paragraph style. Usually single column of unbroken print running from left to right on page. Two-column formats are also common. Used more often for policies than procedures. Not effective with complex, difficult, or lengthy material.

Outline: variation of standard narrative. Text is separated into distinctly shorter sections and subsections, all labeled. Section identified with numbers, letters, or an alphanumeric combination. Can be used widely. Used in both policies and procedures. Logical and easy to follow.

Playscript: Excellent for procedures that involve more than one person or department. In its simplest form, playscript has two columns. The first column tells who’s responsible, and the second describes what’s required. The steps in the second column are in sequence. This form can be adapted. Playscripting’s visual clarity makes it remarkably fast and easy to find information. Highly recommended for any procedure with more than on actor or responsible party. Not appropriate for policies.

Flowchart: a diagram of a process, which uses symbols and arrows to indicate flow and action. Commonly used in procedures than in policies, but can be used in either. Danger of flowcharts is that they can become cluttered and hard to read.

Using the Secondary Formats
Secondary formats are those that are used as inserts inside the primary format. They can stand on their own as primary formats in some highly specialized documents. There are four secondary formats: question and answer, troubleshooting (or help), matrix table, and lists. These formats summarize, clarify, or expand, on the information in the body of the text.

Question and Answer: used in both policies and procedures. Address items that are particular concern to readers. Sections simulate a personal conversation-worded informally. Good places to address the concerns you know readers have about the policies and procedures.

Troubleshooting: also called help sections and sometimes reference sections. Used primarily in procedures. Deal with breakdowns or exceptions. Often presented in chart format, where each problem is listed individually along with solution.

Matrix Table: connect one variable to a second variable. Excellent format to use when readers need to refer repeatedly to the information periodically over time. Eliminates the need for constant rereading and searching. Have wide application.

List: lists break the denseness of the printed page and let the eye skim quickly. Reader gets impression of information relatively easy to grasp and use. Main purpose is to shorten, organize, and clarity.

Combing Formats
All different formats are often combined and these combinations can be very effective. However, do not randomly or excessively change formats, because this can create a consistency problem.

Experiments and Hybrids
None of these formats is sacrosanct. Experiment with them, modify them, and adapt them to your needs. You can combine virtually any format option with any other option.

Thanks for reading our chapter summary! Gary and Jennifer

What's Technical about Technical Writing

Chapter 8: What’s Technical About Technical Writing?
by David N. Dobrin

Team 2: Gary Teagarden and Jennifer Bruns



David Dobrin, the author of this article not happy with an over-simplified definition of technical writing—“Technical writing is writing about technology.” In the introduction of this essay Dobrin notes that he wanted something more about what technical writers do. “And what they do is write or ghostwrite manuals and reports.”

Observes Dobrin: “The reports and manuals appear when there is a technology, a writer, and readers who want to use the technology. When the pieces succeed, they act as a kind of semipermeable membrane that lets understanding leak through at a controlled rate.”

Dobrin trys to come to a more refined, all encompassing definition of technical writing. He looked at pioneering work of several academics in trying to construct a definition: Fred MacIntosh, John Walter, Patrick Kelley and Roger Masse. For example, Kelley and Masse state, “Technical writing is writing about a subject in the pure sciences in which the writer informs the reader through an objective presentation of the facts.”

Writing Technically

“The definers of ‘technical writing’ look at texts; the definers of ‘writing technically’ look at the encounter which produces the texts.” John Harris defines technical writing: “Technical writing is the rhetoric of the scientific method.” In quoting another expert in Earl Britton, Dobrin writes that not only must writing be objective, it must be univocal. That is, “The primary, though certainly not the sole, characteristic of technical and scientific writing lies in the effort of the author to convey one meaning and only one meaning in what he says.

Britton explains that writing is like music. If one wants complexity in music, one writes a symphony. If one wants to wake up soldiers, one plays reveille on a bugle. Literature is the symphony; technical writing is the bugle call.

Dobrin: “The technical writer speaks with the care of a scientist, the humility of a saint, and the clarity of the bugle call.” Talk about an apt metaphor.

Sections within this piece speak of univocality—precise language and only one meaning to the copy in question. More theory is discussed when he discusses the universalist view of language and the monadist view. The nuances of these definitions are confusing and must be read carefully to grasp the differences. Those taking the universalist view believe a sentence can mean a particular thing and that precisely that meaning can be understood. The monadist alternative is to see language as it is actually used, rather than as a formal system.

A New Definition of Technical Writing

After a thorough discussion, Dobrin notes “Technical writing is writing that accommodates technology to the user.” People do not read technical writing for fun, but because they need to do a task. Technical writing gives what is useful, not what is unknown.

He finishes his piece with a take on how people end up in technical writing—typically from two paths: Technicians who learn how to write and writers who learn to excel at technology. Which are you?