Wednesday, September 26, 2007

Barker Chapter 4

Writing to Support – Reference


Barker discusses the third level of the levels of support, reference documentation, also known as support documentation. Barker defines and explains the purpose for the three types of reference information:

Appendices: which allow the documenters a place to put all the highly detailed, technical information that the technical users would want to use in the workplace. The appendix is relevant and useful but may not be essential to all users. Some examples of items in the appendix are:

  • Error messages and explanations of how to recover from them.
  • Filenames and extensions of files associated with the program.
  • Troubleshooting tips.
  • Matrixes of compatibility with other programs.
  • Charts showing program key combinations.
  • Printer driver charts showing capabilities with various printer brands.
  • FAQ.

Update Information Sections/Readme Files: Consist of text files that accompany programs either with an additional disk or download from an internet site. They serve the purpose of informing the user of new information, installation details, last minute changes, new features, etc.


Job Aids: also known as job performance aids, are shorter forms of reference documentation that include keystrokes, definitions, brief processes, command summaries and other information useful to users. The purpose of the job aid is to provide useful information at the point of need. They consist of a number of forms such as; keyboard templates, cheat sheets, laminated program cards, quick reference cards, and other forms. Another variation of the job aid is the innovative forms: Flipcards, the purpose of the flip card is make it easier for the user to simply flip through the information he or she is searching for.

Innovative Forms: Flipcards This section Barker also discusses as an easy to follow format it is technically classified with the job aids. The flip card is valuable because:

  • Easy to read
  • Contains a surprisingly large amount of information
  • Colored headings
  • Unique and interesting
  • Affords easy access to information.

Barker also discusses the importance of what to include in your reference guide, he breaks up the reference specifications into three main groups:

  • Commands: refers to all the instructions the user uses to make the program work.
  • Information about the commands would include:
  • Meanings of special function groups
  • Explanation of set commands
  • Definitions and use of format commands
  • Special procedures for using utilities
  • Explanations of toolbars
  • Definitions of macros

Interface Elements: Refer to the parts of the screen that the user sees and has to manipulate in order to use, these include:

  • Explanations of menus
  • Definitions of keys
  • Labels of screen regions
  • Explanations of rulers

Definitions of Terms (Glossary)

  • Concepts that underlie the software
  • Terms relating to the subject matter of the software

Barker also discusses the importance of organization either alphabetical or menu-by-menu. Menu-by-menu may have more advantage because the user is used to seeing that format. He also states that you should explain to the user how and when the reference guide should be used. It is different from teaching or guidance level of support, it is there to inform the reader not to give a “how to”.

Monday, September 17, 2007

Contesting the Objectivist Paradigm: Gender Issues in the Technical and Professional Communication Curriculum

In her article “Contesting the Objectivist Paradigm: Gender Issues in the Technical and Professional Communication Curriculum,” Lee Brasseur discusses the different aspects of her master’s level “Gender Issues in Technical and Professional Writing and Communication” class and how she is working toward a socially responsible discourse model.

Brasseur begins her discussion by giving a brief history of language practices. She says that scientific language has been about clarity and conciseness, but that it often hides the complexity of the social environment. Scientific rationalism reflects a view of subject/object ideologies, which assume that one’s position is impartial because the human agency is self-defined and self-motivated. Language practices influenced by this outlook promote a disregard for any culture or cultures outside the dominant one. The dominant group naturally imposes an order upon the more subordinate parts of the culture. Science and technology have reflected the views of the dominant group within its culture, which is a “masculinist model of human experience which assigns goodness to certain valued ‘male’ traits such as rational thinking and objectivity” (477). The current understanding of rational judgment is defined by this group’s ideas about human behavior. However, this paradigm is shifting as more critics warn us about its problematic theories and practices. These critics hope to replace the current discourse model with one that emphasizes multiple positions and moves toward a new paradigm of “objective” discourse.

Brasseur then goes on to discuss the need for a course devoted to gender issues in technical communication. Her goals for the class are to communicate to future technical communicators the value of critiquing the traditional technical discourse model and its reliance on gender-based assumptions. She believes that a course entirely devoted to discussing gender issues will help students study the theoretical and practical information that can strengthen their resolve to change outdated and ineffective paradigms. The students in her class, she believes, will learn that although some of the current discourse models in technical communication are effective in an organization, they may also contribute to communication that limits the capacity to promote change.

Next, Brasseur highlights the two course goals for her “Gender Issues in Technical and Professional Writing and Communication” class. The first goal is to introduce students to the “problems inherent in gendered assumptions about rationality and objectivity, as well as the role of feminist theory in addressing these problems” (479). While the second goal is for students to “gain practical experience in addressing these problems by conducting ethnographic workplace studies” (479).

The assigned readings for Brasseur’s course include those that would present oppositional or essentialist views of feminism, and those that promoted situated knowledge. These texts focus on the societal differences between men and women, as well as the different ways of thinking and understanding. Brasseur discusses the difficulty in selecting textbooks, and says her final decision was based on the diverse background of her students.

For assignments, Brasseur’s students responded in essay format to one or two questions that were meant to help them sort out what they had read. In addition to the assigned readings, Brasseur also had her students select their own readings and lead a class discussion about what they had found. To complete her second goal, the students designed a workplace ethnographic study on a topic related to gender issues.

Brasseur then goes on to describe her syllabus for the course. The syllabus consisted of three units, which focused on specific goals for the class. The first unit was centered on the larger problems of discourse models with privilege objective voices. The second unit provided an examination of two central issues underlying this communication model: “the important role that naming plays in determining how we think and communicate our sense of reality,” and “how permanent positionings of domination and subordination underlie any problematic subject/object ideologies” (481). The third unit addressed the social construction of the workplace and promoted the examination of traditional forms of oral discourse. In addition to the three units, the syllabus listed student-selected readings that focused on the topic of women and technology.

Next, Brasseur discusses an essential part of her course design, which is moving from theory to practice. Through the assigned readings, students became aware of the different theories related to technical discourse, and from these readings, they were able to design their own workplace study to help them gain a personal understanding of the complexity of organizational roles of rationality and objectivity. Brasseur taught her students how to perform proper ethnographies, which take place in a “real world” setting and instead of having the traditional hypothesis, begin with a series of general questions. Even though these studies weren’t performed in a short-time period, Brasseur believed they were useful because they offer a different kind of picture than a study performed in a laboratory. The students performed a variety of studies including some with educational settings, one in a bank, and one in a hospital. Brasseur says that greatest value of the studies was that they provided direct examples of gender-based assumptions for her students.

Brasseur concludes her article by discussing the student and instructor evaluations for the course. She says that overall, the students’ responses were positive, and that the only real complaint was the amount of reading. The comments from her students included how they couldn’t imagine a degree without this class and how the class helped them see the relation of feminist theory to technical writing. Brasseur also includes her own set of comments for what she would like to change about the course in the future. These comments include a change in the required texts, and to allow students to choose any workplace situation to study, not just gender. Brasseur ends her discussion by stating that traditional technical models of discourse are normally taught, and that her class provides a different way of thinking about discourse models.

Campbell Chapter 3 - Isn't There a Law Somewhere?

In this chapter, Campbell discusses the legality and consequences of policies and procedures. She starts by stating that as a writer, you have to be familiar with the restrictions imposed by the laws to avoid your organization being sued.

Next, Campbell states some of the reasons you can and will be sued for. They are:
• If the procedures used by customers or employees are unclear, imprecise, or poorly worded.
• If your policy or procedure violates some law or legal precept, intentionally or unintentionally.
• If the wording of your policies and procedures restricts the organization’s ability to act.
• If you have written policies and procedures but don’t use them or don’t enforce them consistently.
• If you fail to state who is responsible for or what the consequences of noncompliance are.
• If your policies or procedures are incomplete, in improper order, or inaccurate.

Campbell then talks about special obligations needed to prevent users from understanding your policies and procedures. These are language barriers and literacy problems. She says that for literacy problems, to make the document written at an appropriate reading level. For language barriers, the document may need to be translated.

Then, Campbell goes on to discuss the different types of violations. The first is a tort, which is simply a wrongful act, one that violates a duty imposed by law, and is grounds for a civil action. Campbell says that you may face court challenges for a variety of reasons including: operational policies and procedures violate safety regulations or pollution laws; administrative policies and procedures violate fiduciary laws or fraud statutes; or if your personnel policies and procedures violate civil right laws or public policy, which refers to actions that may not have any direct statutory protection but are generally recognized as being in the public interest.

The next type of violation that Campbell discusses is negligence, which is the failure to exercise reasonable care in instances where such care is a duty under the law. These claims tend to affect procedures more than policies, but they can happen in either case. They have always been an issue when it comes to product liability because you are obligated to give clear, complete, and reasonable instructions for installation, operation, maintenance, and repair. Negligence can also be found in personnel policies and procedures.

Campbell then goes on to the third type of violation, which is breach of contract. Policies and procedures are considered an implied contract even though they are not signed. The Michigan Supreme Court ruled that contractual obligations exists if the organization creates policies and procedures, then leads employees to believe that they are: established and official rules, fair rules, and rules that are consistently, uniformly applied to all employees. Implied contract claims frequently involve disciplinary or termination matters and are of special concern to personnel policies and procedures. Virtually anything you do or say that could be construed as a policy statement is under scrutiny.

Next, Campbell discusses the importance of disclaimers since users and courts may see your policies and procedures as an implied contract. She says that whatever type of wording you use for a disclaimer, be sure it’s strong, clear, and definite. For internal policies and procedures, a disclaimer should be added that declares that they do not constitute a contract and may be changed at any time. Campbell says that the disclaimer can be placed at the beginning of the handbook, as well as throughout the handbook. For external users, warranty disclaimers and other disclaimers are a means of clarifying responsibilities or consequences.

Then, Campbell discusses the need to update your policies and procedures. Courts expect you to keep people informed of your current standards and rules.

Campbell goes on to discuss the difference between manuals and handbooks. The term handbook may imply information that is widely distributed to a general audience, while the term manual may imply more detailed information that is restricted in circulation to a select audience and is considered confidential. Handbooks may create an implied contract, while manuals don’t necessarily create a contractual obligation to employees as a whole. The term user’s guide is used to avoid contractual obligations because the title implies that the book contains guidelines, not absolutes.

Next, Campbell discusses what the courts want the organizations to do to avoid legal risks. These include:
• Operating in safe, reasonable, fair manner.
• Communicating your policies and procedures clearly.
• Enforcing policies and procedures.

To conclude this chapter, Campbell discusses how to protect yourself. She says that there are no legal guarantees, but you should have the goals of reducing legal exposure and to be in a good position to defend yourself if it becomes necessary. You should focus on two factors: content that is appropriate, sufficient, and accurate and writing that is clear, understandable and precise. These factors fall into six categories:
• Word your policies and procedures carefully.
• Check the content.
• Reserve management’s right to discretionary action.
• Preserve your right to make changes.
• Consider the informal and unwritten rules.
• Use and enforce the rules.

Writing Software Documentation, Barker, Chapter 3

This chapter covers what a procedure is, how procedures work, and what the writer should think about before writing a procedure.

The first item a writer should keep in mind is Relating tasks to meaningful workplace activities (64). Barker continues to say that procedures are parts of a whole and should be written with the clarity of how a procedure fits into the larger picture.

Determining how much information the user needs (66) is the second item on Barker's list. Detail in a procedure increases with the degree of difficultly of the procedure. A good rule of thumb is the more detail, the more visuals and explanations should be present. Barker outlines some different ways to enrich procedures:
  • Layering information for different users, those who already know part of the procedure and those who are learning for the first time.
  • Screen shots provide the users with a visual of what to do next.
  • Cautions & Warnings provide the user with advanced knowledge of how to retrieve information should it be lost.
  • Tips for efficient use help the user by offering an alternate method for accomplishing a task, or elaborating on a step or command.
  • Tables allow for efficient organization of information. A few uses for tables in procedures are to present information on features and uses as well as terms and definitions.
  • References to other sections of the manual or procedure or other resources
  • Explanations of any step or command

Choosing the appropriate procedural format (72) can have a major impact on how well received your procedure is. Four formats that are covered in this section.

Standard format which contains steps, notes, screen shots, and other elements left justified in one or two columns in a sequential order from first to last. Advantages of this format are its recognizability, its ease of flow from one page to another, the ability to easily re-number tasks, and the easy to see steps. Some disadvantages are the space it may require and the potential to be confusing if complex steps need to be mixed with simple steps.

Prose format puts steps in sentences and paragraph forms making it look and feel more conversational over Standard format's command approach. Advantages of prose are the relaxed tone, saves space, clarifies simple, basic steps, accommodates experienced users. Some disadvantages are steps buried in paragraphs, lengthy explanation of individual steps, inability to accommodate graphics, and the lack of support for novice users.

Parallel format shows a screen with the fields empty and parallels the field names in the steps that follow. This format is nice for programs with complicated data fields of dialog boxes. Some keys to parallel format are to keep terminology consistent, cue terms to the screen, discuss one screen at a time, use plenty of examples, explain the format to the user. Advantages of parallel format are the organizational benefits, great for complicated screens and dialog boxes. Disadvantages are it doesn't present the information in step by step format, it can not be used for all procedures, it may confuse users, it has to fit on one page.

Embedded help is the name for "interactive assistance" found in most programs today. Uses for embedded help are tips for effective use (reminders of keyboard shortcuts or suggested file names), cue cards (brief explanations of buttons and fields), short animated descriptions, and trouble-shooting tips. Different types of embedded help are:

Flyout help Help that appears in a box or panel on the screen at the user's request.
Interactive flyout help. This form monitors the user's progress in filling out a dialog box and highlights one step at a time until the procedure is complete.

Do it for me help this form of help contains links within the online help procedure that activate the screen element or dialog box described in the procedure.

Field-level help Help that provides information on how to enter information in fields.
Interface help. Help information (brief instructions) provided in a designated section of a screen.

Pop-up definitions Pop-up definitions provide brief definitions of interface elements activated by a mouse click.

Roll-overs Definitions of interface items that appear when you move a mouse over the item and (often) pauseFollowing a rhythm of exposition (80) means consistency through out the procedure. An example of rhythm of exposition is:
  • First I give command for the step.
  • Then I say how the program will respond.
  • Then I illustrate what happened.
  • Then I tell the next step.

Test all procedures for accuracy (81). Always conduct usability tests for your procedure to ensure that they are effective and correct.

The Discussion section (81) of this chapter begins with what constitutes a procedure. Procedures are used when a user is doing something with the program. Procedures function on the guidance level by telling the user which key to press next, what screens and reports will come up next, and how to get out of trouble. Procedures differ from the teaching level because procedures are geared towards what should be done at any given moment rather than a tutorial of the program. Procedures differ from support level reference documents in that procedures follow a chronological or sequential order.

Procedures work by maintaining a general layout of information. Each procedure should have a project-orientated name, i.e. Opening a file, or Recalling a Record from the Client Database. The task name is followed by an overview or introduction that orients the reader to the use of the procedure, reminding the user what the task will allow them to accomplish in a work setting. Following the overview are the steps. This aspect is the most important because it is the period of time that affects the user directly. Great care should be taken when writing the steps so the user does not get confused or lost. Methods you can take to try to ensure the user fully understands your procedure are placing smaller actions in prose format under the parent action or elaborating on a parent action, i.e.

  • Step 1. Choose Group from the Maintenance Menu.
  • Step 2. Choose an action from the Groups dialog box. Once you have opened the Groups dialog box, you need to select a name for the group, then select a directory name for the group, then set the access code to either Open or Restricted.
  • Step 3. Choose Close from the Groups dialog box.Elaborations help explain the steps as they are performed, which can help the user to avoid potential mistakes and perform procedures more efficiently.

Elaborations can also tell the user about alternative functions, toolbars, or keystrokes, how to tell if a step has been performed correctly, or where to look for additional information.Options or tables are suggested for use in procedures by organizing information and saving on space. These should be used when defining different keystrokes for the same operation, i.e.


To do this... Use these keys...

  • Set colors to black and white Ctrl-M
  • Revert to default colors Ctrl-D
  • Adjust the brightness Ctrl-B
  • Adjust the tones Ctrl-T

Screen shots, or screens, should be used when the user needs to see a tool in use or the results of an action. Screens are usually used for the following:
  • Give an overview of the main panel of an interface
  • Show the partial result of a procedure (a stage in the process) to help the user keep on track.
  • Show the final result of the procedure to let the user know where the procedure ends.
  • Show dialog boxes where the user has to make choices.
  • Show toolbars indicating which tools the user needs.
  • Show menus indicating what commands the user needs.

Sunday, September 16, 2007

Feminist Theory and the Redefinition of Technical Communication

Mary M. Lay

Mary M. Lay discusses the need for the redefinition of Technical Communication to involve a more feministic approach. Lay speaks of technical communication in the past as known for the affiliation with scientific research. As of the 1980’s and 1990’s technical communication has adapted ethnography and anthropological research methods. It has included them to involve within the workplace environment. This is when Lay develops her concern for feminist theory.
Lay is concerned with the matters of objectivism and ethnography in means of collaboration. Lay defines her theory with six categories that discuss feminist qualities and three categories that define debate among feminists.

Characteristics of feminist theory include:
1. Celebration of difference
2. Theory activating social change
3. Acknowledgment of scholar’s backgrounds and values
4. Inclusion of women’s experiences
5. Study of gaps and silences in traditional scholarship
6. New sources of knowledge – perhaps a benefit of the five characteristics above

Lay goes on to discuss the six points stating that women celebrate difference because they do not want to be defined in a general sense. That women value new knowledge and hope that leads to a better understanding. In terms of research women will place themselves on the same level as the subject of the research to better understand that subject. Women value their experiences as well as others and try to relate. Women will explore the unknown and criticize the original study or definitions. Five refers to the knowledge and information that women receive is compared to historical moments and past experiences, instead of an individual person or instance. Lastly, that self image is not just personal experience but is interpreted by others.

Lay goes on to discuss the three issues of debate among feminists:
1. Should feminists emphasize similarities or differences among men and women?
2. Should these differences be located in cultural or biological traits?
3. Should these first two issues promote or displace binary opposition?

The first debate talks about the differences or similarities among men and women. Lay talks about whether these characteristics should be accepted or if a state of androgyny should be erected.
Next she discusses whether these differences should be recognized as cultural or biological. She brings up the maximalist approach which is there are basic differences between the sexes and that they are essentially culturalistic. The minimalist position states that men and women are essentially similar and the gender differences are superficial and socially constructed.
The third issue is dealing with masculinity and femininity whether they should be separate and if so women are placed below men on a hierarchical scale.
Lay goes on to talk about objectivity, scientific method, and ethnography. Basically Lay is telling her audience that technical communication is formerly known as research and not only research but quantitative scientific method research that doesn’t leave much room for a subjective approach. Now that technical communication has evolved so should the definition. Women or more predominant in technical communication than before and ethnography is a more popular research method. Lay is trying to ask the question how is research methods presented by women going to change technical communication, in the sense that when women do research especially ethnography they will have different backgrounds and influences then that of men. Women are inherently more nurturing and concerned about feelings. In the matter of collaboration which Lay thinks will be the most effected, she discusses the potential conflict and difference between men and women and how the conflict would be resolved. Most importantly Lay questions whether these should be issues for technical communication and if so what kind of definition would be given to technical communication in the future.

Tuesday, September 11, 2007

Barker - Chapter 2 Summary

Writing Software Documentation: A Task-Oriented Approach

Thomas T. Barker

Chapter 2 – Writing to Teach: Tutorials

This chapter focuses on the first of Barker’s three forms of software documentation: tutorials. Barker begins the chapter by explaining its objective, which is to offer “examples, guidelines, and discussion” for designing effective tutorials. He continues by describing tutorials as a form of documentation that involves focused lessons which guide a user through a process, assuming that their proficiency with the software will increase as they practice using it to complete tasks.

Barker divides the content of the chapter into two main sections, Guidelines and Discussion.

Guidelines

Barker presents a series of guidelines that are meant to provide a basic procedure by which one can create effective task-oriented tutorials.

Step 1 – Identify User Actions You Need to Support

Barker recommends performing a thorough user analysis to determine the actions and scenarios that would be most relevant to a particular use. Within an organization, it is possible that a single piece of software will be used in different ways by different employees. It is useful to identify and list program skills that a user will need to accomplish specific tasks. Some criteria that can help in selecting which program features to focus on include the degree to which those features are:

  • Central to job performance
  • Essential for efficient software use
  • Performed frequently

Another way of approaching this challenge is through an embedded tutorial (or EPSS) that detects when a user may need help on a particular topic and presents itself automatically at that time.

Step 2 – State Objectives as Real-World Performance

Tutorial writers, Barker asserts, should carefully define the learning objectives that they would like their users to achieve, and then state them for the user at the start of the lesson. These should inform the user, in measurable terms, what they will be doing in the tutorial and what skills the activity will impart to them.

Step 3 – Choose the Right Type of Tutorial

Barker describes several loose categories of tutorials, which serve different purposes depending upon the situation. The Guided Tour is an overview of program features that informs and persuades the user as to the usefulness of the program in a low-interaction environment. The Demonstration is a more focused presentation of a particular program function being performed, which tends to be passively viewed by users. The Quick Start is a form of documentation that is generally aimed at more advanced users and provides the basic information that one needs to dive into the program and interact with it on their own. A Guided Exploration guides a user through a procedure, but allows for some experimentation on their own. The most traditional form of tutorial is the Instruction Manual, which attempts to teach as much of the software as possible through a full series of interactive lessons.

Step 4 – Present Skills in a Logical, Cumulative Structure

A key component to effective tutorials is arranging the various lessons in a logical structure. This is often accomplished by organizing the lessons procedurally in accordance with typical workplace scenarios. Common cumulative structures include such progressions as beginning to advanced, generalized to specialized, and using default options to using customized options.

Step 5 – Offer Highly Specific Instruction

By soliciting very specific actions and information from their users, tutorials promote real-world skill building as well as confidence and interest in the program. Some examples of specific instructions include:

  • Specific data
  • Tools
  • Screens
  • Commands

Step 6 – Give Practice and Feedback at Each Skill Level

Barker recommends maintaining a highly positive tone throughout the tutorial, and praising users for their accomplishments whenever possible. He also advises building a pattern of exposition, by which the tutorial writer continuously:

  • Gives an action to take
  • Explains the results

Keeping lessons short (under an hour and ideally 10-12 minutes) will help make the tutorial more accessible to busy users. Including a convenient means by which one can pause a tutorial and return to it later is also beneficial.

Step 7 – Test Your Tutorial

Like any documentation, tutorials should undergo a thorough usability test. There are a variety of methods for doing so, but the most revealing information often comes from observation of an actual user making use of it in a realistic scenario.

Discussion

In this section, Barker explores the different elements that make up tutorials, and two philosophies of teaching that can inform tutorial design decisions.

Designing to Teach

Here, Barker offers some advice on how to decide when it is appropriate to use a tutorial versus some other form of documentation. Important considerations include the nature of the tutorial as a learning activity, and its narrow focus on achieving a very specific goal.

Selectivity in Choosing Material

In determining which procedures warrant tutorials, Barker asserts, one must rely on their user analysis. In doing so, a documentation writer will likely build tutorials based on the most common scenarios that their users will encounter.

The Elaborative vs. Minimalist Approach

Barker defines the elaborative approach as a theory of teaching that emphasizes comprehensive coverage of a topic, with the help of “summaries, explanations, examples, and articulations of goals and objectives”. Some research has shown that this approach can help users apply what they have learned to real-world situations more readily. This approach is consistent with Barker’s six principles of lesson design:

  1. Instruction results in articulated skills.
  2. Skills transfer capability to real-world performance.
  3. Steps should present skills in a logical, cumulative structure.
  4. Highly specific instructions work best.
  5. Give practice and feedback at each skill level.
  6. Master one skill before going on to the next.

Barker describes the minimalist approach as one that expects a certain impatience from documentation users, and attempts to serve them accordingly. He quotes John Carroll’s observations that documentation users often tend to:

  • Forego introductory or orienting documentation and dive right into interacting with the program
  • Skip information that does not appear immediately relevant
  • Resist restrictive instructional strategies and assert creative control over the learning process

Barker also references Carroll’s four principles adhered to by minimalist manuals:

  1. Choose an action-oriented approach
  2. Anchor the tool in the task domain (workplace context)
  3. Support error recognition and recovery
  4. Support reading to do, study, and locate

Ultimately, the decision to use an elaborative, minimalist, or hybrid approach depends on the situation and the professional judgment of the documentation author.

Barker concludes the chapter with a glossary of terms and a checklist for evaluating tutorials. He also includes a number of tutorial analysis exercises.


Sunday, September 9, 2007

Campbell Chapter 2 - Where Do I Start?

Campbell begins this chapter by discussing the importance of not skipping preliminary steps when trying to write an effective document.

Next, Campbell goes on to address the four steps to development, which is the preparation prior to drafting. The four steps are:
• Planning
• Analysis
• Research
• Prewriting
The time it takes to get through each of these steps depends on both the writer and the document. Campbell also notes that each step is needed in the correct order to make a successful document.

Campbell then begins her in-depth description of each of the steps, starting with planning. She says that a plan must be developed, and it is normally should be done in writing. The plan can be simple, but it should always be completed before any actual writing occurs.

The first part mentioned by Campbell is to set a schedule. She notes that schedules can be as simple as a piece of paper, or for more complicated projects, a Milestone or Gantt chart can be used. These charts show time frames for each step, and can also include personhours, assignees and overlapping steps. Campbell makes a point that schedules should not be skipped because without them, a deadline will surely be missed.

The next part of planning that Campbell discusses is using a team. She notes that because of the nature of some projects, a team works better than a single person. Team writing has both benefits and disadvantages like any team activity. Campbell says that success depends on good organization and clear communication.

Then, Campbell goes on to discuss being realistic, which is the last part of planning. She says you must again think about time frames, team members, possible conflicts and “brick walls,” and consider if they are realistic goals. Frustration is largely avoidable with realistic planning.

The next step in the four steps of development is analysis. Campbell describes analysis as a “realistic look at the audience, the assignment, the context in which it’s been made, how much and what types of research are required, and the conditions under which you’ll have to work.” She says to begin an analysis with the “what” and “why” of the project. Look at who is requesting the project, examine the reasons for the request and finally look at the nature of the project.

Campbell says that after the nature and reason for the request is known, one should be sure to understand the goal and the desired end result of the finished policy or procedure. If the goal of the project is not clear, this is the time to go back to the requestor for more information. Campbell states that you can’t help readers understand the importance of the policy or procedure if the writer doesn’t understand it.

Another part of analysis that Campbell notes is audience. She says that the more one knows about the audience, the better choices the writer can make in content, wording, format, and design of the document. The experience, education, preferences, expectations and attitude of the audience should all be considered.

Campbell then goes on to discuss the other elements to be analyzed when starting a project. She writes about conditions of document use, the urgency of the document, the impact the document will play on the organization and the project conditions. The analysis step is concluded by going back to the requested with updates. Campbell notes that writers have to sometimes fight for the resources to do the job, and these must be clear to the requester.

The third step to development is research. Campbell says that when this stage is reached, the writer is taking the first real action on matters of content. The amount of research is determined by the analysis of the project.

Campbell says that one should start with the most difficult, complex information, since it takes the longest to study and understand. She says to resist the urge to start with the easiest research first. Starting with the difficult research gives you time to ask questions, get clarification and resolve misunderstandings.

A writer should talk to content experts, but not stop there. Campbell suggests talking with anyone that holds information about the project. She says to talk to both internal and external people to gain insight about the project. To properly interview these people, the normal etiquette of informational interviews should be observed. One should have a list of prepared topics and questions, and the interviewee should be informed about the reasons of the interview. Campbell emphasizes the need to take notes. She says that a standard form of notes is good when interviewing a large number of people. These notes are the foundation of your document’s content, so Campbell says to take them carefully and accurately.

Campbell goes on to discuss soliciting information in writing, which is sometimes necessary if individual interviews aren’t feasible. She says to keep the solicitation as simple as possible and to remember that written requests are generally less effective.

Campbell then goes on to explain reading and studying. She says that when interviewing and surveying are not sufficient or possible, one should explore books, articles or trade publications that contain current, relevant material. Campbell suggests looking through organizational files, suggestion forms or comments during meetings, current policies and procedures, libraries and the Internet.

A final note Campbell makes about research is to concentrate on the critical information because a writer seldom has time to locate everything that’s out there on a given subject.

The final step Campbell discusses is prewriting, which is the missing link between the preparatory steps and the actual document. She says it organizes the material and speeds the drafting. Before drafting begins though, the material needs organized. A writer should have accurate and complete content, good organization, and logical flow before they start writing.

Campbell notes that a mind-map is a simple way to get all possible content concerns out on the table before the writing begins. She says the mind-map works better than starting with an outline because often content gets left out in a structured, numbered list. Mind-mapping eliminates the rigid list and lets the random, creative side thrive.

Campbell concludes this step and the chapter by stating that after the information that should be included is decided, it must be placed in the proper sequence. She says to create an outline of the mind-map by combining key words, phrases, sentences or paragraphs. The material should be put in a sequence or flow that’s logical to the reader, not necessarily the writer.