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.