You are here: Articles --> 1995–1998 --> Notes on the documentation development process

Vous êtes ici : Essais --> 1995–1998 --> Notes on the documentation development process

Notes on the documentation development process

by Geoff Hart

Previously published as: Knapp, P.; Hart, G.J. 1996. Notes on the documentation development process. Internal document written for software developers [Revised for republishing on this site by Geoff Hart based on an early draft and the original e-mail that appeared in the techwr-l discussion group]

Before starting

Try to develop a close working relationship with the other team members. Make regular meeting times to keep in touch. Set goals for the team.

Define your audience, and their needs, explicitly and carefully. The definition process may lead you to include additional material such as indexes, system requirements, and contextual notes (e.g., lists of exceptions), as well as the preplanned documentation.

Create a simple but effective method of learning about new software or changes in the software, so the changes can be documented. This is the best time for the writer to demonstrate the need for interaction with the team, and what happens if interaction does not occur in a timely manner.

If the product is still changing rapidly when the writer must start work, begin by planning and structuring based on the audience analysis. Fill in the details as the product becomes stable.

Steps for completing the documentation.

1. Define product features.

Verify that you know what your users will do with the software (i.e., 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. Understand why each feature is useful to this audience. Informal definitions (i.e., tacit, spoken) are insufficient. Definitions must be written and cross-checked.

Try to identify subject-matter experts for each component of the project, and persuade them to participate actively in reviewing your material. If you can't obtain access to subject-matter experts, identify other individuals (e.g., product users) who can help. Do not hesitate to ask for help from upper management.

Create a formal documentation plan, including any need for online or printed tutorials. Define as much as you can explicitly in writing, and ask all participants to review the final specifications that you produce. Get signoffs from the various authorities involved. Define or find definitions for standards, both internal and external.

2. Create a mockup of the user interface.

This is the time to perform some pen-and-paper usability testing if you can't do the real ting. Any little bit helps at this stage, because mistakes that you make now will come back to haunt you later. It's also the best time to plan your online help. This is the ideal time to produce a documentation plan that defines all deliverables (e.g., each component of the documentation), the assumptions underlying each deliverable, and the consequences for missing deadlines for each deliverable or for providing an inadequate deliverable.

Keep a binder of printed screenshots for each screen, and update each printout as features change (particularly between versions). Final screenshots can be produced once the software is frozen, but all screenshots must be verified against the final documentation and the final software. Developers often create small cosmetic changes without informing the technical writer, and when the screen differs from the documentation, the users tend to get upset.

3. Begin documentation of features and interface.

You can't finalize anything and identify the delivery date until the product is stable. A good rule of thumb is to plan for the documentation to be ready for the printer 2 weeks after the user-interface freeze. (Of course, this depends on the size and complexity of the product: large and complex projects can clearly take longer.) Depending on how stable things are at this point, you may not be able to do more than create a good outline and some background information.

4. Freeze features and interface.

If you can, freeze the product early. If this is not possible, establish a coping method (e.g., clear notification of any changes when the changes are proposed, not when they are implemented). Strong support may be needed from the project manager. Recognize that all freezes must be followed by thaws that can occur during alpha and beta testing. The documentation writer must be involved in the analysis of the results of the testing so that the writer knows what changes will result from this analysis.

5. Complete the documentation.

In many cases, this stage may not be reached before beta testing begins. If the software changes at all, the documents must change to match.

6. Begin beta testing.

Make sure that some form of the documentation gets included during beta testing, since it may be the your only chance to receive audience feedback. Carefully define what you expect the testers to focus on. If you want them to focus on the typography, tell them. If not, tell them to focus on instructions, phrasing, or specifically whatever you feel that they need to test. Sometimes, providing a test script of focus areas is invaluable.

Resources permitting, beta testing should not be a passive process. Stay in touch with at least a subset of the beta testers, and probe for specific points. Pursue anything interesting that may lead you to change the documentation and development strategy, either wholly or in part.

7. Revision and final distribution.

Some changes will occur after beta testing. Formally identify these changes, and how your documentation will deal with them. Follow up with the product manager to make sure the response is adequate and has been implemented correctly. Triage may take place at this point by dividing changes into: (a) items that must be addressed instantly, (b) items that will be addressed if there is time, and (c) items that can wait until the next revision.

8. Final notes.

Conclude with a reward for the whole team. If the project was completed successfully and in reasonable time, the team has definitely earned a reward!

©2004–2024 Geoffrey Hart. All rights reserved.