Campbell chapter 6

Campbell Chapter 6

How Do I Get Them to Read This?

Campbell discusses the importance of not just creating a sound document but getting people to read your document. The first point she brings up is credibility. People need to believe your advice is going to help them and be accurate. Next she discusses hooking them, not only is it important to have credibility but she brings up the statistic that 70% of what you know about people is based on their appearance (page 206). Readers need to be able to easily tell if the document is clear, easy to read, and concise. Readers want to instantly know if this is going to be worth their time or could they figure it out on their own faster. This brings up the importance of visual appeal. Readers will think that a document is easier if it looks easy to read and clear. Campbell says that there are twenty different design elements: sentence length, paragraph length, line spacing, typestyle, typeface, emphasis, paragraph spacing, justification, indentation, margins, headings, graphics, visual weight, contrast, color, symbols, columns, lists, forms, and white space. She brings up the importance of avoiding visual clutter, which she compared to an attic or garage that no one wants to look at so they shut the door.

Campbell tells the reader that the human brain can only retain seven different items at once but can only clearly distinguish between three of the seven items. That is way the rule of three was created. The rule of three is based on not using more than three different design elements in one document.

Eye movement is an important concept to understand. Campbell talks about the limits that the eye has:

1. Takes in approximately forty characters at once.
2. Takes in three or more words per second.
3. Reads two or more words at one time.
4. Moves from top to bottom and left to right, in a zigzag or Z pattern.

That is why short sentences and paragraphs are extremely important in your document. This is also why Campbell recommends chunking your information. Campbell defines chunking as breaking the printed matter down into chunks the reader can deal with easily. Another technique used to help the reader is white space. White space simply refers to the white or non-printed area of your document. It does not however have to be white it is whatever your paper color is. The last point Campbell discusses is being consistent. Being consist in your language, your design, and your overall appearance. She talks about the reader finding his or her rhythm this helps the reader continue reading and understanding.

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

Campbell discusses the importance of not just creating a sound document but getting people to read your document. The first point she brings up is credibility if people are going to believe your advice is going to help and them and be accurate. Next she discusses hooking them not only is it important to have credibility but she brings up the statistic that 70% of what you know about people is based on their appearance (page 206). Readers need to be able to easily tell if the document is clear, easy to read, and concise. Readers want to instantly know if this is going to be worth their time or could they figure it out on their own faster. This brings up the importance of visual appeal. Readers will think that a document is easier if it looks easy to read and clear. Campbell says that there are twenty different design elements: sentence length, paragraph length, line spacing, typestyle, typeface, emphasis, paragraph spacing, justification, indentation, margins, headings, graphics, visual weight, contrast, color, symbols, columns, lists, forms, and white space. She brings up the importance of avoiding visual clutter, which she compared to an attic or garage that no one wants to look at so they shut the door.
Campbell tells the reader that the human brain can only retain seven different items at once but can only clearly distinguish between three of the seven items. That is way the rule of three was created. The rule of three is based on not using more than three different design elements in one document.
Eye movement is an important concept to understand. Campbell talks about the limits that the eye has:

• Takes in approximately forty characters at once.
• Takes in three or more words per second.
• Reads two or more words at one time.
• Moves from top to bottom and left to right, in a zigzag or Z pattern.

That is why short sentences and paragraphs are extremely important in your document. This is also why Campbell recommends chunking your information. Campbell defines chunking as breaking the printed matter down into chunks the reader can deal with easily. Another technique used to help the reader is white space. White space simply refers to the white or non-printed area of your document. It does not however have to be white it is whatever your paper color is. The last point Campbell discusses is being consistent. Being consist in your language, your design, and your overall appearance. She talks about the reader finding his or her rhythm this helps the reader continue reading and understanding.

Barker Chapter 6 - Planning and Writing Your Documents

Barker begins this chapter by stating that there are nine phases in the documentation process. He says that the key to producing quality documentation is to follow a process. The process Barker describes in this chapter has phases that build on the previous one, and each imply testing procedures and ways for documentation managers and writers to check their progress.

1. Start the Project
The first phase Baker explains is to start the project. He says the start of a project is for you to get to know the software you’ll be writing about. Also, most software documentation is created by two types of teams: development and writing.

Barker then goes on to describe the two teams in greater detail. The development team develops the entire product: software and documentation. These teams are normally assembled from a group of professionals with varied skills. The following is a list of members you can expect to find: Product Developer, Project Manager, Market/Systems Analyst, Technical Specialist/Programmer, and Documentation Specialist. The writing team just develops the documents. The writing team deals with developers, programmers, and others involved in the whole project, but these programmers and developers serves as subject matter experts and not members of the immediate team. The following is a list of members you can expect to find on a writing team: Manager, Lead Writer, Writer, Editor, Graphics Designer, and Tester.

Barker also discusses the need for preliminary research. The users are analyzed and the justification for software gets written down in what are known as project documents. Depending on the company or organization developing the software, you will find variations of the following types of documents: Project Plans, Program Specifications, Market Analysis, Information Plan, and Management Plan.

Barker then shifts his discussion to choosing online media and the special considerations for developing help systems. He says it basically follows the nine-step list, but it often includes extra steps because of the technical aspects of help. The development stages mirror the development of a user’s guide except for these key differences: user analysis, mastering the authoring environment, linking to the software program, testing the help system, and testing in different user environments. Barker provides a brief overview of the process of developing online help. He writes that you must first select the right authoring environment. He gives a list of some of the most well-known authoring environments and suggests looking at the following features to decide which one is right. These include: single-source capabilities, authoring features, management features, and types of help formats supported.

2. Perform the User Analysis
During this stage, Barker writes that you research a number of elements pertinent to effective software use, mainly focusing on the workplace activities of your users that involve software. You use the elements described in chapter 5 to properly determine the user type. The activities in the user analysis should allow you to group the program operations for your table of contents. A default user table of contents describes the functions of the program but fails to reflect anything about the use of the program for meaningful workplace activities. On the other hand, the task-oriented version is grouped by workplace activities and focuses on a process of learning.

3. Design the Documents
Next, Barker states that during the design phase, three types of documents forms are applied to the user’s needs: tutorial, procedures, and reference. Also, at this stage, the titles of the documents are written and you finalize what they will look like. For online help, you decide the types of products you will produce. During this phase you set out the content and look of your document, but decisions at this phase are important for planning, and may change over time.

4. Plan the Documentation Project
Barker then goes on to describe planning the documentation project. If you are managing a project you need to know how to write a project plan so your team members can have a guidepost and keep up with deadlines. A well-organized and quality document is the result of a carefully planned project that makes the most of the users, the writers, and programmers on the team. The key document to organizing a documentation project is the documentation plan. The project plan culminates your research and design work on a project.

Barker suggests making a list of project events and sharing it with the other people on your team for approval and input. He also discusses the three main parts of a project plan, which are: schedule of events for completion of your project, plans for using resources, and time/page estimates. When scheduling a documentation project, you should include the overall phases as well as the following six kinds of events: meetings, deadlines for drafts, project report due dates, test completion, review deadlines and edits. You will also need to plan human and material resources. To assign people to tasks, Barker suggests keeping in mind the following characteristics: writing skills, editing skills, software tool skills, experience with the subject matter of the program, knowledge of the user and the user’s workplace, and familiarity with the development environment. Barker gives an example of what to follow for estimating time/page estimates, but he notes that a number of variables could change this estimate. These include: type of documentation, availability of information, experience of writers, and reliability of the program.

Barker notes that your documentation plan should undergo thorough testing and review by managers, clients, and users. The documentation plan gives you the opportunity to hold a user and technical walkthrough.

5. Write the Alpha Draft
According to Barker, the alpha draft represents your first complete document, including all the front matter, text, graphics, appendixes, indexes, and associated documentation set materials. This draft is tested, reviewed and edited.

6. Conduct Reviews and Tests
Barker writes that since your alpha draft contains all the elements of your product, you can send it out for review. You can also design usability tests. Information obtained in this step provides feedback for the next draft of the set.

7. Revise and Edit
The reviews and the tests from the previous step provide feedback from external sources. Barker notes that revising and editing also allow you to submit your work to an editor that checks for accuracy on many levels. Barker notes that more editing and revising documentation and online help is covered in Chapter 9.

8. Write a Final Draft
Barker writes that if you do the previous two steps thoroughly, you fill find that your document improves greatly at this stage. Barker notes that the final draft of a help system mainly consists of preparing the help file for distribution with the finished program.

9. Conduct a Field Evaluation
Barker explains that after the user has installed and operated the program, the last stage of the development process happens: the field evaluation. This test allows you to gauge how well your manual met the task needs of the intended user. To conduct a field evaluation of a help system, you can use feedback links in the HTML system and use email links.

Barker then goes on to discuss the two main types of projects: stand-alone and development projects. He writes that a stand-alone project is where you are assigned or contracted to write documentation for a software application that has already been written or is being revised. The development project occurs in organizations that create software as their main products. There are differences between the two in three areas: team structures, work processes, and kinds of development documents required.

Next, Barker describes the differences in detail. He says that in stand-alone projects, writers have the entire program at their disposal before they start. In development projects, the writers are involved in the project from the design stages onward so they have more input into the usability and interface of the project. Also, in stand-alone projects, writers follow the nine-phase process listed above. On the other hand, in development projects, they follow one of three main development methodologies, which are: the waterfall method, the rapid-development method, and the object modeling method. Barker gives descriptions of each method. The waterfall method depends on understanding the users’ requirements at the beginning of the project and then carefully designing a system to meet them. Ideally, each phase is done before the next begins. The rapid-development method uses a process of usability testing and prototyping to test designs out during development. Once the right design is found, the program is complete. User requirements are refined as the product unfolds. The object-modeling method uses a complex system of symbols and descriptions to create an abstract design for the system that can be turned into software and documentation with a high degree of consistency.

Barker concludes this chapter by discussing the documentation plan. He says that you should set for yourself a number of goals, among them efficiency and logic in the whole process. You should also make sure your documentation plan is persuasive, and Barker lists the following strategies to help with this: use an executive summary, have a goal orientation, do the math, and show a team orientation. He also suggests ways to make the documentation plan easy to follow. These include: standardizing your terminology, including sample pages, and not stinting on detail in the outlines. Barker also includes the two parts of a documentation plan, which are describing the manual and help, and describing the documentation project. The first part describes the design plan, while the second part describes the project plan. Barker adds that your design plan should describe the users, set out the documentation objectives, provide outlines of individual documents and lay out individual documents. Finally, Barker ends the chapter by giving an outline for a documentation plan.

Nancy Allen et al. - Collaborative Writing

What Experienced Collaborators Say About Collaborative Writing
Nancy Allen, Dianne Atkinson, Meg Morgan, Teresa Moore, and Craig Snow

Introduction

The article begins by explaining how recent research into writing on the job has uncovered the interesting issue of collaborative writing. There exists very little research focusing specifically on this topic, however. Information about collaborative writing, the authors state, is “fragmentary and unfocused”. The authors then cite studies that allude to collaborative writing in the workplace. These include research by Paul Anderson; Faigley and Miller; Odell; Paradis, Dobrin, and Miller; and several others. The peripheral nature of collaborative writing information in these studies cause the authors to state, “from these studies we gain little in the sense of the details or range of variation in the processes collaborative writers user, few clearly articulated reasons for employing a collaborative effort…and no coherent evaluation of collaboration from the writers themselves.”

The scant research that does exist on the topic of collaborative writing reveals a range of activities in which these writers engage. These include scenarios such as staff-written/supervisor-edited documents, collaborative planning with individual drafting, individual drafting with collaborative revising, and coauthoring, among others.

These many different forms of collaborative writing compel the authors to clarify their definition of the topic. They cite a paper by Wiener, who distinguishes between “group work”, a basically individual effort that is supported by a group, and “collaboration”, in which all group members share responsibility for the final product and must achieve consensus in order to produce it. This is the form of collaboration on which this article chooses to focus.

The article identifies two problems in reviewing the existing research. The collaborative writing process itself is poorly understood, and studies have not focused specifically enough on collaborative situations involving group authorship. For this reason, this study focuses on answering the following questions:

· What kinds of people form collaborative-writing groups and what kinds of tasks do they undertake?
· What are the writing processes used by experienced collaborators?
· What significant group processes emerge in collaborative-writing groups?
· How do experienced collaborators feel about the costs and rewards of collaboration?

Methods

In this section the authors discuss their research methodology, describing the project as “an exploratory study of the experiences of active collaborative writers from the business and professional worlds.” The participants were chosen to represent a wide range of collaborative settings and projects. The authors go on to provide specific demographic data about the subjects. They then discuss the structured interview form that they made use of. This form began by soliciting demographic information about the participants, then when on to ask questions about the membership of the collaborative writing groups that they have been a part of, the roles and contributions made by members, the writing process used, the types of group interaction that took place, and their overall evaluations of the experience as a whole. These questions were asked over the course of a two hour interview.

In the first stage of analysis, transcripts of the participants’ responses were referenced to produce basic demographic profiles of the members and their projects. In the second stage, the participants detailed observations and evaluations were collated.

Research Findings

The authors concede that their small sample size makes the information gleaned from their study incomplete. Demographically, the participants represented a wide variety of collaborative writing tasks, covering many different forms of professional documents. They also note that participants tended to want to talk about projects that they deemed successful, versus failures. The types of groups with which the participants had worked were diverse in nature in that some were made up of members with very different backgrounds and skills, while other groups had very similar membership. Most groups knew the type of document they would be producing and its general format, while others had higher or lower levels of task restriction.

The group writing processes that the participants engaged in always began with collaborative planning activities. This was usually followed by relatively independent research and drafting. Different participants reported different scenarios. Some produced drafts after heavy group planning, then revised based on group discussion. In some groups, everyone produced a draft, and in subsequent meetings members attempted to merge them. In other groups, the members contributed sections based on their specialties. Sometimes group members attempted to write collectively, word-for-word, a practice which often led to frustration.

Most participants reported significant interaction between group members early in the project, usually face-to-face. The article identifies three important aspects of group interaction:

Group as First-Line Audience

The group often served as an initial audience for the piece that they were writing, unconsciously or consciously.

Group Conflict

Conflict seems to be a given with collaborative writing (or as one respondent put it, “collaborative fighting”), but can benefit the process in many ways.

Computer-Aided Interaction

Computer-mediated communication was not nearly as prevalent at the time this article was written as it is now, however, some of the participants in the study had made use of computers to communicate with other collaborators on writing projects. This included both text-based communication, and sharing of drafts.

Decision-making power in the collaborative writing groups was shared in that anyone in the group could contribute suggestions or object to any idea. This power, however, was completely limited to the writing task at hand. There was a great deal of commitment to the process and the group among members.

Most of the groups were structured around group leaders who primarily seemed to serve a coordinating function. However, there were leaderless groups which prove that this is not necessarily a defining feature of collaborative writing.

Most respondents greatly appreciated the benefits of collaboration, finding them well worth the costs of time, energy, and ego. The documents that they produced collaboratively, they rated as “satisfied” or “very satisfied”. The subjects all recommended collaboration.

Discussion

The research results suggest three important points.

Functions of Conflict

The authors present several studies that support their participants’ suggestions that conflict increased group creativity. These include Janis, Weick, Rothenberg, and others. “When the group can tolerate some disharmony and work through divergent opinion to reach a consensus, their work is enhanced,” the authors conclude.

Distinguishing Shared-Document Collaboration

Here, the article presents a new term for describing a certain form of collaborative writing: shared-document collaboration. Such writing must involve production of a shared document, substantive interaction between group members, and shared decision-making power and responsibility.

There are many advantages to forming collaborative writing groups. The authors found that such groups are formed primarily because of the size of the task, the scope of the task, or a desire to merge divergent perspectives.

Questions for Further Research

The authors conclude their article by conceding its exploratory nature, and reiterating that their small sample (many of whom have academic affiliations) can only yield partial results. They also point out that since their subjects chose to speak mainly about successful projects, they have little data regarding failed collaborative writing projects. Future research on this topic could explore the influence of leadership styles, the use of multiple group types and writing processes on a single project, new technologies, and the interaction between organizational hierarchies and the hierarchy of collaborative writing group members. From business to academia, more information on collaborative writing would be immediately useful. The authors hope that they have pointed the way to future research.

Barker - Chapter 5 - Analyzing Your Users

Writing Software Documentation: A Task-Oriented Approach
Thomas T. Barker

Chapter 5 – Analyzing Your Users

Intro

Barker begins the chapter by giving an overview of what user analysis entails and why it is valuable. User represents the “basic research phase of the documentation process”, and involves “contact with persons who might use the software that you want to document. It involves inquiry into eight areas:

1. Tasks and activities the user will perform
2. User’s informational needs
3. User’s work motivations
4. Level of the user’s computer experience
5. User’s knowledge of the program’s subject matter
6. User community
7. User’s learning preference
8. User’s usage pattern

The answers to these questions will assist throughout the documentation process, informing the goals for the documents and what they will cover.

1. Choose Users Carefully

You begin this process by listing every potential type or group of potential users of the software as possible. You can then narrow down this list to those whom represent typical users and with whom you can form a working relationship throughout the documentation process. This selection process should involve consideration of each user’s unique culture.

After assembling this list of users, you will conduct a series of interviews with these individuals to build a list of common job tasks that would benefit from documentation.

2. Anticipate Transfer of Learning: Study Users Before and After Tasks

You should begin by determining the activities of users, “without the benefit of your program”. When you understand about the duties and skills of your users, you can craft your documentation in such a way that facilitates the transfer of these pre-existing skills to the operation of your software.
It is also important to build up a repository of tacit knowledge about users, which includes all of the small facts, attitudes, artifacts, interactions, and values that guide them in their job duties.

3. Research Professional Behaviors

In situations where direct user contact is impossible or insufficient, it is possible to research professional behaviors to construct a “mock-up of the user”. There are many resources for learning about the job duties of individuals in a particular position or industry, including occupational guides, industry-specific guides, placement services, or company job descriptions.

4. Write Use Cases

Use cases are descriptions of typical job scenarios, based on the tacit knowledge that comes from uncovering the “motivations, behaviors, values, and knowledge pertaining to your users that might not be visible on the surface.” By employing use cases in your documentation, you provide role models for your users. Use cases can also be included in the documentation plan to illustrate the types of activities that will be supported.

Work flow diagrams, which graphically depict organizational processes, are often a useful accompaniment to a use case. Barker also suggests that you should be mindful of your limited resources, and restrict your documentation accordingly.

5. Plan Interviews Carefully

Effective software documentation should “encourage [users] to learn the features of the program and put the program to useful work.” To this end, interview questions should involve users in the whole documentation cycle, using a usability approach.

Familiarity with the developers of the program and the program itself should help inform the questions you will have for users. Investing time in an interview plan can greatly increase their productivity. General steps for interview planning include:

1. Do preliminary research into the user’s job and programs already in use.
2. Review the software program and indentify the issues.
3. Establish the scope of your interviews.
4. Make a list of interview questions.
5. Get permission.
6. Set up and interview schedule.
7. Plan a follow-up.

Barker also recommends attempting to assess the verbal style of the users and reflecting it throughout the interview process to solicit better answers.

In addition to interviewing, observation can be a useful tool for gathering data about your users. This involves shadowing users at their place of work and recording their various actions, while taking care to avoid:

· Getting too involved – such that you distort their activities.
· Not getting involved enough – such that you focus on the wrong details.

Questionnaires are also valuable in that they allow you to gather information from a variety of users, increase the chance of identifying unique concerns, and identify wide patterns of use. For best results, these questionnaires should make use of open-ended questions, include clear instructions and plenty of room for filling in responses, and avoid negatively-worded questions.

6. Involve Users in All Phases of Project

A full user analysis should involve users in every stage of the documentation process, including writing, reviewing, and testing. This results in many benefits, including:

· Increased accuracy
· More appropriate information
· Increased usability
· Improved relationships

The relationship between the documentation writer and the users is an important one. Including them in the process yields valuable information regarding their specific situated action in the organization. This allows you to become a user advocate, bridging the gap between the software program’s users and developers. This relationship will also benefit from embracing the work culture of the users.

Conducting focus groups is another way to involve users in documentation, and are a good way to spark new ideas. Tips for conducting a successful focus group include:

1. Locate potential participants.
2. Develop and administer a telephone screening questionnaire.
3. Confirm invitations in writing.
4. Draft open-ended questions and follow-up questions, then revise.
5. Plan any hands-on activities.
6. Make reminder calls.
7. Pilot-test the questions with one or two group members.

Encouraging user participation in this way helps “extend the possibilities of user-centered design.”

7. Identify Document Goals

It is important to communicate your documentation goals early in the process. These consist of statements expressing specific objectives describing how the documentation will encourage users to learn the program and use it effectively. “The clearer your objectives,” states Barker, “the better the chance that you will achieve them.”

8. Tie the User Analysis to Documentation Features

It is important that the features that you document are chosen based on specific user needs. By tailoring this information to specific users, a more usable document results.

Discussion

User analysis is of central importance when composing task-oriented documentation. It incorporates the users’ workplace context, personal needs, organizational goals, work culture, and many other factors. This can assist you in a number of ways, such as by revealing ways in which users will use the software, providing scenarios and examples for use in tutorials, and identifying potential topics for testing, among others. Ultimately, a well-done user analysis will help “unify your document set”.

Software use is always situated in a user’s workplace and cultural context. Effective documentation will take this into account, and reflect “the user integrating the program instead of just the program.” Eight questions that help provide this tacit knowledge include:

1. What tasks will the user perform with the program?

Knowledge of job roles provides a starting point in describing user actions. Workplace activities exist in a context of information. Barker suggests focusing on a few key tasks to use as cornerstones within your documentation.

2. What are the user’s informational needs?

Often, software users may require some knowledge that is outside the realm of the program itself in order to use the program effectively (e.g. graphic design principles for a user of page layout software). It is useful to identify any such information and direct your users to the relevant resources.

3. What are the user’s work motivations?

Awareness of how users’ tasks shape their information and communication needs will help you to identify users’ underlying motivations. Interface elements should therefore take this awareness into account, and be arranged into “meaningful sequences leading to an objective” that is of value to the user.

4. What’s the user’s range of computer experience?

There are many differences between novice, experienced, and expert software users. It is important to pay attention to these differences and target your documentation to the learning patterns of the appropriate audience, or multiple audiences, when necessary.

5. How much does the user know about the subject matter of the program?

Subject matter knowledge influences the amount of supporting detail required when describing operations. This professional knowledge is also referred to as domain knowledge.

6. What’s the user’s workplace environment?

Various forms of user communities can often provide a great deal support to software users. These include help forums, special interest groups, newsgroups, user groups, web resources, newsletters, third-party documentation, FAQs, web rings, and mailing lists. You should strive to direct your users to these resources when appropriate.

7. What’s the user’s preferred learning preference?

Individuals accumulate knowledge in different ways based on a variety of factors. Whether the information is being delivered by an instructor, manual, or computer-based system, it is important to take into account factors such as the learning setting, the source of information, variations in information delivery, and the various forms of media used.

8. What’s the user’s usage pattern?

Usage patterns describe how users interact with the software over time. These can be: regular – involving daily use, intermittent – regular and frequent but at irregular intervals, or casual – an immediate need for use exists, but with little or no formal training yet received.

Barker concludes the chapter with a glossary of terms, a checklist for performing a user analysis, and some case studies with which to practice.

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

In chapter 5, Campbell begins by discussing how to choose a format for policies and procedures. The best format depends on whom you’re writing for, what kind of material you’re dealing with and whether management accepts the format.

When determining your format, you should first ask yourself who your audience is. Campbell writes that certain formats are better for particular types of people. Engineers, scientists, and those with a technical background prefer flowcharts, while they might confuse other people. Readers respond better to formats they’re familiar with. However, unfamiliar formats don’t necessarily mean a bad choice. If the old format is ineffective, it is wise to switch. If using an unfamiliar format, Campbell suggests making time to introduce and explain it to your readers. Sometimes an organization requires a certain format, but if it seems confusing, occasionally organizations will make a parallel document, which is more user-friendly.

Another thing Campbell says to consider when formatting your document is the material. The nature of the information narrows your format options. Safety procedures require absolute clarity, so you want a format that is clear at first glance. In this case, a standard narrative format won’t help the reader much, and a flowchart could work much better. Campbell writes that you should examine the nature of the material closely before you settle on a format.

The final aspect of format consideration is management. Since upper management authorizes the policies and procedures, they must also understand and support the document and its contents. Campbell writes that you must ensure management’s comfort level, which is just as important as that of other readers.

Campbell then goes on to discuss how to decide a page layout for your document. She writes that the page layout gives the reader certain information about the policy or procedures, such as title, number, or effective date. This information is usually found in the header. A full header with all of the information typically appears on the first page, and a shorter version appears on the remaining pages. If the information is substantial, it is sometimes split into a header and footer. In other page layouts, certain parts of the text are standardized and are put immediately preceding the policy or procedure but outside the header. Campbell writes that the amount and types of information you standardize are up to you. The goal is to keep the document simple so the standardized information doesn’t detract attention from the policy or procedure itself. Once you decide what the readers need to know, you decide where and how to place it on the page.

Next, Campbell discusses choosing a format among the options. She writes that once you decide on a page layout, you are ready to choose a format from the main text. The primary options are: narrative, outline, playscript, or flowchart. These options are often used in combination with each other. The secondary options are: question and answer, troubleshooting, matrix table, and list. They are known as secondary because they can’t be inserted into the main document format. Campbell notes that once you choose a primary format, you must use it consistently throughout your document.

Campbell then goes on to discuss the primary formats in-depth. She first discusses narrative, which is the standard sentence-and-paragraph style. Standard narrative format is usually a single column, but two-column formats are also common and are used to break up sold horizontal lines of print. Narrative format is used more for policies than procedures. Campbell notes that narrative is not effective with complex, difficult, or lengthy material.

The next primary format Campbell discusses is the outline, which is a variation of the narrative format. The text is separated into shorter sections and subsections. These sections are labeled with numbers, letters or alphanumeric combinations. Campbell writes that the outline formats can vary widely, and that the format depends on the material you’re working with. She also notes that it is used in both policies and procedures because it is easy to follow.

Next, Campbell writes about the playscript format, which is great for procedures that involve more than one person or department. In the simplest form, a playscript has two columns. The first column tells who’s responsible while the second column describes what’s required. This format can be adapted for more complex procedures. The playscript is clear and provides an instant visual clue to the reader so they know what’s relevant to them. Campbell notes that when you use a playscript for the first time, you should explain it briefly to the readers.

The final primary format Campbell discusses is the flowchart, which is a diagram of process that uses symbols and arrows to indicated flow and action. Flowcharts are more commonly used in procedures than policies. Campbell notes that a danger of flowcharts is that they can quickly become cluttered and hard to read.

Campbell then goes on to discuss using secondary formats. The main purpose of these formats is to deal with other possibilities that may arise and special conditions that may exist. Campbell begins by discussing the question and answer format, which are used in both policies and procedures. They contain questions that a majority of readers might ask and are designed to simulate a personal conversation.

The next secondary format Campbell discusses is troubleshooting, which are used primarily in procedures so users aren’t forced to reread the entire document to get help when there’s trouble. Campbell writes that troubleshooting sections are often presented in chart format so the problem can be solved quickly.

Next, Campbell discusses matrix tables, which connect one variable to a second variable. She writes that matrix tables are a good format when readers need to refer repeatedly to the information periodically over time because they eliminate the need for constant rereading and searching.

Campbell then goes on to discuss lists, which should be used often because the eye loves lists. Campbell writes that lists break up the denseness of the printed page and let the eye skim quickly. An indented group of related items is known as a displayed or vertical list, but there are also other types, such as paragraph, nested and parenthetical. Lists allow you to use shortcuts what would sound odd in a regular sentence. These include leaving out the subject and starting with a verb, leaving out articles, and using partial sentences or only key words. Campbell notes that the main purpose of the list is to shorten, organize and clarify.

Campbell concludes this chapter by writing about combining formats and experimenting with different formats. She notes that you can switch among the formats for clarification, but to be cautious as to not overwhelm the reader. The formats should be experimented with in a search for better ways to communication important information with clarity and speed.

Campbell - Chapter 4: What’s the Best Way to Word This?

Writing Effective Policies and Procedures: A Step-By-Step Resource for Clear Communication

Nancy J. Campbell

Chapter 4 - What’s the Best Way to Word This?

Technical vs. Narrative Writing

Campbell begins the chapter by attempting to explain the technical writing style. The writing that most of us learned in school, she terms “narrative” writing, a style which makes use of “complex grammatical structures” and is often descriptive, lengthy, and complicated. Policies and procedures, she argues, should employ a form of technical writing that emphasizes clarity and speed of transmission.

The Old Rules

In this section, Campbell reiterates her belief that our educational system equates verbosity with quality. Policy and procedure authors, she concludes, must shed this inappropriate mindset.

The New Rules

Effective policy and procedure writers, Campbell asserts, adhere to the maxim, “Simple is good.” She decries padding, complex sentence structures, and fancy vocabulary.

Being A Word Miser

In the pursuit of verbal simplicity, Campbell suggests that text should be limited to only those words absolutely necessary to convey the intended message. She offers several tips to help in achieving this goal:

Think in Ones

Eliminate unnecessary adjectives, prepositional phrases, and extra clauses, using only those words necessary to convey your main point.

Dump Pompous, Stuffy Language

Eliminate “windy, stiff language” by following Campbell’s word miser rules, to be discussed later.

Speak to the Reader

Try to write as though you were speaking to your reader in person. Avoid the “flabby, excessive writing”, that comes from dressing up common words (e.g. use→utilize, start→initiate, etc.).

Follow the Word Miser’s Rules to Live By

The use of active voice clarifies roles, and writing in the present tense gives a desirable sense of immediacy. This is true, suggests Campbell, even when these techniques lead to the use of improper grammar.

Be an Accurate Word Miser

Here, Campbell reminds her readers that brevity should never come at the cost of clarity. When cutting words, do so judiciously to avoid introducing uncertainty and confusion.

The Word Miser’s Rules to Live By

Here, Campbell summarizes her suggestions in a list of 17 rules for effectively communicating policies and procedures. Many of these are accompanied by examples.

1. Use common words and phrases.

2. Use one- and two-syllable words.

3. Get rid of windy phrases.

4. Get rid of redundancies.

5. Get rid of empty phrases.

6. Eliminate all unnecessary adjectives and descriptions.

7. Limit the number of clauses and phrases, and keep them short.

8. Use short sentences.

9. Use short paragraphs.

10. Use one-sentence paragraphs.

11. Keep phrases and clauses short.

12. User transitions at the start or sentences and paragraphs to tell readers what’s happening next.

13. Use lots of lists.

14. Use active voice.

15. Use present tense.

16. Start with an action verb.

17. Use standard word order of subject-verb-object.

Being a Word Master

In this section, Campbell offers additional tips for becoming a “word master”, or “one who uses words with precision and respect”. These include:

Say What You Mean and Mean What You Say

It is important to be mindful of the vast range of possible misunderstandings inherent in even the simplest of phrases. This requires precision in communication, which may trump the goal of brevity.

Use Specific Language

Policy and procedure writers should avoid words that invite varying interpretations. These include “weasel words” such as “may, might, could, should, etc.” Each of these words has a precise meaning that must be fully understood.

Developing a Rhythm

Here, Campbell introduces the concepts of consistency and parallelism, which contribute powerfully to reader interest and comprehension.

Consistency

Varying words and terminology can confuse readers, so use terms consistently throughout a document. This is one area in which creative wordplay can degrade clarity.

Parallelism

Parallelism simply refers to the technique of using the same grammatical format for like items. Varying grammatical constructs makes instructions awkward to follow.

Being Correct

It’s extremely important to avoid mistakes in grammar or usage, states Campbell. Such errors can lead to confusion, misinterpretation, and mistakes. To help avoid these issues, policy and procedure writers should refer to style guides as needed.

Considering the Reader

This section offers information on writing in such a way that is relevant to one’s readers. It assumes that one has performed the audience analysis.

Don’t Assume Anything

Do not overestimate the knowledge or experience of your audience.

Look at the Reader’s Experience

Reexamine your audience analysis, and in most cases, target your writing to your most inexperienced readers.

Use Jargon Carefully

Some considerations regarding jargon include:

• Even experienced users may not be familiar with it.
• It can be cumbersome and difficult to understand.
• It can be faddish and pompous.

Distinguishing Between Users and Readers

When writing policies and procedures, give precedence to the needs of your users over those of your readers.

Calculate Reading Level

Make use of software-based or manual reading level calculations to ensure that you are writing at an appropriate level for your audience. This is frequently in the range of a 6^th-8^th year reading level.

Word Documents Carefully

Using words that provoke unpleasant reactions will reduce our audience’s receptivity to your message.

Using Special Techniques for Procedures

Special technical writing techniques exist that can help maintain a high level of clarity when writing, thereby reducing the serious risks associated with unclear policies and procedures.

Start With an Action Verb

Policy and procedure users are generally looking for an answer to the question, “What do I do?”. Beginning one’s sentences with action statements offers them a clear reply.

Use One Action per Sep

Steps that contain more than one action “confuse the reader and bury the message”. Most procedures should be broken down into their most basic, individual steps. Exceptions to this may be made in cases where the nature of the procedure is such that combining steps increases the clarity of instruction.

Assign the Action

When there are multiple actors involved in a procedure, it is important to clearly state who is responsible for each step of the process. Avoid using indefinite pronouns.

Pack a Sentence

Readers tend to remember the first and last parts of a sentence best, so in some cases it is useful to arrange your words to capitalize on this phenomenon.

Choose the Right Format

Adhering to strict format guidelines can help a policy and procedure author adhere to all of these suggestions automatically.

Tools and Resources

Campbell concludes her chapter with a collection of lists, tip sheets, guidelines, and formulas to aid in the construction of policies and procedures.