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.
12 comments:
It is interesting that we are actually going to be using one of the authoring environments mentioned in this chapter--Authorit. Although I am somewhat nervous about this endeavor, I am excited at the prospect of learning an authoring environment in this course.
Thanks for a great summary of this chapter!
I found this to be a very detailed chapter. Certain parts were helpful to me, particularly the user analysis procedures, which I anticipate using for our group usability test. However, other parts, such as the discussion of team members, weren't as useful for me. Because I haven't worked for large organizations, the details of the development team were interesting but not applicable to me.
I found this chapter to be somewhat confusing on my first read because of the organization and all of the italicized terms. I thought the summary was a very helpful review, and I feel much more comfortable with the terminology and content after having read it. I think some of the guidelines presented here will be helpful in completing the documentation project, and am looking forward to learning more about Author-IT.
I was surprised by the placement of Design the Documents at step 3 of the guidelines. Whenever I create a document, I get a good first draft done before I begin working on the specifics of the design. I don't think I'll be able to ever work on the design before having the bulk of my research and writing complete. Why do you think they place this step so early in the process?
This is a great chapter. I really liked the extent of detail-- and good summary. From authoring programs to usability testing to writing the alpha draft (never heard it called that). This chapter shows the amount of work that goes into a classic writing project. A lot!!
I was very interested in the steps this chapter listed. I had never really considered the concept of certain "steps" before this chapter - I guess in the past, I just always wrote until things were complete. However, I do think I follow the steps, even though I didn't realize that I did.
Nice job!
I thought the chapter was full of useful information. I think the ability to follow a plan is the key to a successful document--especially delivering the document on time. No matter the size of your organization, you can still plan a document from start to finish. I'll certainly keep the concepts in mind when I begin to undertake a large project.
I liked this chapter because of the way it listed the steps. However, I plan the documentation second with regard to the assignments I have been doing here. It is very interesting that we are going to be using a documentation software that is mentioned in the book, I look forward to learning more about it once I actually get into it.
In response to Mary's post, perhaps doing the page design early gives the writer time to adjust the design later, if necessary. Also, having a general idea of the layout and design might help the writer identify weak points in the documentation. I don't know--I'm just guessing. From the comments that have been posted, it seems like people are used to a more "freewheeling" process. How accurately do the guidelines in our texts reflect the actual workflows of real technical communicators?
Working as project manager, I really valued the topic of this chapter. Most of the projects start as a thought, then maybe grow within a meeting, then they end up drafted on paper. At that point they are laid out, initially a rough skelleton with major timelines, man hours, deadlines and a budget estimate. As time progresses, the timeline is refined and updated. There is much similarity between project management and the planning and writing process of creating documents. In fact, being and getting organized before the (writing) project starts really cuts down the overall project time in the end.
I haven't worked in an organization where group writing projects have occurred, so I don't know first hand the challenges of writing documentation. My preference would be to be involved in the process early on rather than jump in at some stage along the way.
I find it interesting the author recognizes the liklihood that the writer will spend time learning the author software. Hmmm...I'm a little concerned about that as well.
I, too, found the end-of-chapter summary the most useful.
The chapter is a good summarization of project development. Thanks for writing a thorough and concise summary.
I can see how this chapter would be a launching pad for group work in large organizations, as it seems to focus on such scenarios.
While some of the steps, I think, can be done in a different or flexible order, the chapter seems to give us a firm direction.
Post a Comment