|
–Geoff-Hart.com: Editing, Writing, and Translation —Home —Services —Books —Articles —Resources —Fiction —Contact me —Français |
You are here: Articles --> 1995–1998 -->Teamwork and the product documentation process
Vous êtes ici : Essais --> 1995–1998 -->Teamwork and the product documentation process
By Geoff Hart
Previously published, in a different form, as: Hart, G.J. 1997. Teamwork and the documentation process. Intercom, July:4–7.
If you spend any amount of time in the technical writer's discussion group (techwr–l) on the Internet, you'll inevitably encounter people expressing their frustrations about having documentation treated as an afterthought to product development. When my employer recently took on the task of developing software for some of our clients, it occurred to me that we had an opportunity to impose a more or less structured approach to the process of documenting our software.
The goal of such a process would be to make our publications group part of the software development team. We could then work with the developers to produce accurate, effective documentation that would be ready when the software was due for release. Another important element would be getting input from users—during both the design phase and the testing phase.
I spent some time reading up on the subject and then created a skeleton of what I considered to be a functional process. I posted this skeleton to techwr–l and asked for suggestions on adding some muscle to its bones. Since my original posting of the results, I've had the opportunity to forward the process to others in my position. The results appear below.
There are several things you should do right from the start:
In addition, there are three final stages you'll be involved in:
The most important thing you can do to become part of the product development process is to develop a close, amicable working relationship with the other team members. You'll be prevailing upon their kindness throughout the development process, which could extend over months or years, and things will go much more smoothly if they perceive you as an ally. Even if you can't develop a truly friendly relationship (for example, if you're working in another city), try to keep in touch about more than just work. As an editor, I find that talking to my authors about personal interests, rather than exclusively about manuscripts, builds successful and mutually enjoyable relationships.
Be honest about this. Don't pretend an interest in seventeenth-century pottery if the subject bores you. But do be willing to listen patiently when the person feels inclined to discuss their favorite topic.
Create some simple but effective method of learning about changes in the software so that you can account for these changes in the documentation. The process must be as simple as possible, because if it becomes a burden, people will take shortcuts. This is a great time to educate your fellow team members about the need for interaction and about what happens (such as the proverbial undocumented feature) in the absence of interaction. If your organization has a formal mechanism for tracking changes (e.g., groupware or a changes database), you may succeed simply by gaining access to this resource and monitoring it for changes.
At the other end of the spectrum, attending design meetings so you can hear about proposed changes may be all you need to do. One useful approach is to act as recording secretary at these meetings: By freeing the product developers from this task, you also earn some credits with them that you can redeem later. (Some writers resent taking on a "secretarial" role. Don't be one of them. This is your best chance to really learn what's going on.)
In terms of the product, define your audience and their needs, explicitly and carefully, before you start. This axiom of writing has been stated so often that most of us take it for granted. In my own case, we have a small, homogeneous, and interested audience with whom we've worked closely for 20 years; as a result, we know them far better than most writers know their audience. You'll probably have your work cut out for you. The process of defining audience needs may lead you, for example, to create only a reference manual, or an exclusively task-based manual. The process may also lead you to include additional material such as indexes, system requirements, and contextual notes (e.g., lists of exceptions).
If you have time, try to meet your users face-to-face. For more information on this, see Customer Visits: Get to Know Your Audience in the June 1997 issue of Intercom.
Verify that you really know what your users will do with the software (e.g., perform a task analysis) and that you understand their language and work habits as well as you think you do. Specifically define the audience in terms of tasks and how they talk about the tasks, and understand why each feature of the product is useful to this audience. Informal (i.e., spoken) or tacit definitions are inadequate. This stage may also be your best time to create a documentation style guide that addresses these issues.
Try to identify subject-matter experts for each component of the product, and persuade them to participate actively in reviewing your material. If you've developed a friendly working relationship with the development team, you may already have this stage under control; if not, your final resort may be to appeal to management to guarantee this access and cooperation. If you can't obtain access to subject-matter experts, which may be the case if they're at a different work site, try to identify other individuals who can help. For example, the product's users may also be experts in the subject you're documenting, even if they don't know the product itself.
Create a formal plan that defines your documentation needs, including any online or printed tutorials and marketing materials. Define as much as you can explicitly, in writing, and ask all participants to review the final specifications that you produce. If you can, get signoffs from the various authorities involved: The act of signing something and accepting responsibility for its accuracy and completeness sometimes focuses a reviewer's attention marvelously well on the task at hand.
Don't forget that there may be internal (e.g., corporate) and external (e.g., ISO, government) standards that you must meet, and that you must explicitly address them in your plan.
This is a great time to perform some "pen and paper" usability testing if you can't do the real thing. Every little bit of testing helps at this stage, because mistakes that occur early during the development will come back to haunt you later. Simple testing is also a great way to plan the outline for user aids such as online help. Revise your documentation plan accordingly to better define the deliverables (that is, each component of the documents, the assumptions that underlie each one, and the consequences of missing the deadline for a deliverable or producing an inadequate deliverable).
It's helpful to keep a binder full of visual references on your product. For software, these most often take the form of printed screenshots. Update each printout as features change; this task becomes particularly important if you're producing a revision of an earlier version of the product. You can finalize your graphics once the product is frozen (see below); indeed, you must verify them against the final product to confirm that there have been no last-minute changes. (Developers often make small cosmetic changes without informing you. These can prove greatly disconcerting to the users if the product differs from the documentation.)
You can't finalize your documentation or identify when you can deliver it until the product is stable: "The doc clock starts when the UI is frozen" (attributed to Peter Hartman). Sue Gallagher, one of my techw–l reviewers, tells her clients that "the documentation will be ready for the printer two weeks after the user-interface freeze", which is a difficult standard to meet, but possible if your documentation process is efficient. (Longer times may be required for large or complex projects, of course.) Depending on how stable the product is at this point, you may not be able to do more than create a good outline and begin collecting the necessary background information. At the very least, answer the question, "What you can do with this software?"
Plaintive tales of documenting a moving target are a fact of life for technical communicators. The rule of thumb seems to be that the features or user interface of a product won't "freeze" until moments before the product ships, no matter how well you plan. If you can persuade developers to freeze the product early on, do so. If you can't, try to establish some method of coping: At a minimum, create some mechanism for obtaining clear notification of any last-minute changes when the changes are proposed, not after they've already been implemented. To do this, you'll need strong support from the project managers.
Recognize that all freezes may be followed by thaws; for example, beta testing may well lead to significant changes that undo the freeze. Once you're aware of the development team's plans for usability testing, get involved in this part of the development process, too. At a minimum, get a copy of any analysis of the results of the testing so that you'll know what changes are likely to result from this analysis. You can begin to complete the documentation at this point, but it's unlikely that you'll actually finish this early. In some cases, documentation may be quite incomplete by the time beta testing begins. Don't be discouraged if you're playing catch-up at this stage.
Make sure that some form of the documentation gets included at this stage, even if only an outline and a "getting started" guide. This may be your only chance to obtain feedback from your audience. Carefully define what you expect the testers to focus on. If you want them to focus on the typography, tell them so, but if not, ask them to ignore that factor. A test script of some sort that focuses their attention may be invaluable.
Resources permitting, try to be actively involved in beta testing. As much as possible, stay in touch with at least a subset of your beta testers, and probe for specific points. Pursue anything that may lead you to change all or part of your documentation and development strategy.
Some changes will inevitably occur after beta testing. Formally identify these changes and how you'll deal with them, and then follow up to verify that your response is adequate and that you have implemented the response correctly. Since the marketing department is desperate to ship the product at this stage, you may have to resort to triage: some things you must address instantly, others you can address if you have time, and still others will have to wait until the next revision of the product.
The biggest problem you'll encounter at this stage is the delay between the time you send your documentation to the printer and its return for packaging along with the product. Depending on your relationship with the printer, the time of year, and the number of copies you must produce, this delay can range from weeks to months. For example, the text for a glossy monthly magazine is often finalized 3 months before the magazine hits the newsstand.
If you're working with a typical development team, this means they have time to modify the product beyond recognition after you've "finished" the documentation. Plan how you will cope with such modifications. For software, including a "read me" file on the installation disks is the most common solution; for hardware, the equivalent is a printed list of errata inserted into the shipping carton at the last possible instant.
The final step, from a purely human perspective, is to reward yourself and your teammates. If you've survived the chaos of documenting a product, you've earned this reward. Even something as simple as a noon pizza party for the development team will suffice, and it has the additional benefit of enhancing working relationships within the team.
In many ways, you should consider this article a "construction kit" for building the rudiments of your own process, not a final result that is ready to implement. For a considerably more detailed approach, I recommend JoAnn Hackos’s book Managing Your Documentation Projects.
One thing I haven't covered is the issue of budgeting resources, whether financial or human. If you need to give your manager a resource budget, I recommend that you consult Joyce Lasecke’s Stop Guesstimating, Start Estimating in the November 1996 Intercom.
In my own case, developing a documentation process has taken much longer than I thought. I've built most of the necessary working relationships with our developers, but have only recently obtained formal Management buy-in to developing a process. Management is open and receptive to the idea, but took a long time to make the final commitment necessary to implement the process. As this anecdote shows, organizational inertia sometimes becomes a powerful obstacle to an effective process. In such a case, the best you can do is to identify the stages where the process is likely to break down and come up with solutions to get you past those stages. Over time, you can gradually implement the process you desire, or modify an unsatisfactory process so that it at least works better.
I thank the following techwr–l participants for contributing invaluable advice based on their personal experiences: Art Elser, Sue Gallagher, Bonni Graham, Sue Heim, Donna Menk, Robbie Rupel, Emily M. Skarzenski, Bill Sullivan, and Chris Thiessen. For information on how to join the discussion, visit the techwr–l Web site.
Hackos, J.T. 1994. Managing your documentation projects. John Wiley and Sons, Inc., New York, NY.
LaSecke, J. 1996. Stop guesstimating, start estimating! Intercom, November:5–7.
Ray, E.J. 1996. Techwr–l: a history and case study of a profession-specific Listserv list. Technical Communication 43(4):334–338.
©2004–2024 Geoffrey Hart. All rights reserved.