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