Establishing a documentation process

[geoff-h -at- MTL -dot- FERIC -dot- CA]

 Some time back, I asked for help in imposing a structure on
 our current chaotic process for producing documentation for
 upcoming software. Here's what we've come up with so far
 (feel free to add to this summary):

 0. Before starting
     Try to develop a close, amicable working relationship
 with the other team members: you'll be prevailing upon
 their kindness for some time, and things will go much more
 smoothly if you start out amicably. Even if you can't
 develop this sort of relationship (e.g., you're working in
 another city), try to keep in touch about more things than
 just work... this is what builds successful and mutually
 enjoyable relationships.
     Define your audience, and their needs, explicitly and
 carefully, before you start. (In _our_ context, this has
 already been done surprisingly well, but we have a small,
 very homogeneous captive audience that we've worked closely
 with for 20 years. Very few development projects arise in
 such a context.) The definition process may lead you, for
 example, to create an exclusively 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).
     Create some simple (i.e., not a burden on anyone) but
 effective method of learning about changes in the software
 so that you can account for them in the documentation. This
 is a great time to educate your fellow team members about
 the need for interaction, and what happens if the
 interaction doesn't occur.

 1. Define product features
     Verify that you really know what your users will do
 with the software (i.e., a task analysis) and that you
 understand their language and work habits as well as you
 think you do. (This is a good time to create a docs style
 guide!) Specifically define the audience in terms of tasks
 and how they talk about the tasks, and understand why each
 feature is useful to this audience. Informal (e.g.,
 spoken), tacit definitions are insufficient.
     Try to identify subject matter experts for each
 component of the project, and persuade them (via the
 Management "big stick" approach if necessary) to
 participate actively in reviewing your material. If you
 can't obtain access to subject matter experts, identify
 other individuals (e.g., the product's users) who can
 help.
     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. (Ideally, get
 signoffs from the various authorities involved.) Don't
 forget that there may be internal (e.g., corporate) and
 external (e.g., ISO, government) standards that you must
 meet, and you should explicitly address how you'll do
 this.

 2. Create a mockup of the user interface
     This is a great time to perform some pen and paper
 usability testing if you can't do the real thing. Any
 little bit helps at this stage, because mistakes that you
 make now will come back to haunt you later. It's also a
 great way to plan your online help. This is an ideal time
 to produce a documentation plan that defines all
 deliverables (e.g., each component of the docs), the
 assumptions underlying each one, and the consequences for
 missing deadlines for each deliverable or producing an
 inadequate deliverable.
     It's helpful to keep a binder full of printed
 screenshots for each screen, and update each printout as
 features change (particularly between versions). You can
 produce final screenshots once the software is frozen
 (see below), but you must verify these shots against the
 final documentation (e.g., no new buttons added since
 last screenshot) and the final software (e.g., no
 last-minute changes to interface). Developers often
 create small cosmetic changes without informing you, and
 you can greatly disconcert users when the screen differs
 from the docs.

 3. Begin documentation of features and interface
     You can't finalize anything and identify when you can
 deliver it until the product is stable: "The doc clock
 starts when the UI is frozen" (attributed to Peter
 Hartman). Our very own Sue Gallagher adds: "The
 documentation will be ready for the printer two weeks
 *after* UI freeze", a tough standard to meet but worth a
 try. 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 ("what you can do with this
 software").

 4. Freeze features/interface (if not already done)
     We've seen lots of plaintive postings about documenting
 a moving target; the rule of thumb seems to be that the
 "freeze" may not occur until moments before the product
 ships, no matter how well you plan. If you can freeze the
 product early on, do so. If you can't, at least try to
 establish some method of coping (e.g., clear notification
 of any last-minute changes at the stage where the changes
 are _proposed_, not after they've been implemented). This
 _will_ require strong support from the project managers.
     Recognize that all freezes must be followed by thaws;
 for example, "beta testing" (see below) may well lead to
 significant changes that undo the freeze. (Get involved in
 the analysis of the results of the beta testing so that
 you'll know what changes will result from this analysis.)

 5. Complete the documentation
     In some cases, you may not reach this stage before beta
 testing begins. Try, but don't be disappointed if it
 doesn't happen. If the software changes at all, the
 docs must certainly change.

 6. Begin beta testing
     Make sure that some form of the documentation gets
 included at this stage, since it may be your only chance
 for feedback from your audience. Carefully define what you
 expect the testers to focus on. If you want them to focus
 on the typography, fine, but if not, tell them to ignore
 the type. In some cases, providing a test script of some
 sort is invaluable.
     Resources permitting, don't let beta testing be a
 purely passive process. As much as possible, stay in touch
 with at least a subset of your beta testers, and probe for
 specific points. Pursue anything interesting that may lead
 you to change your documentation and development strategy,
 in whole or in part.

 7. Revision and final distribution
     Some changes will inevitably occur after beta testing.
 Formally identify these changes, and how you'll deal with
 them... then follow up to make sure your response is
 adequate and that you have implemented it correctly. (You
 may have to do triage: items that you must address
 instantly, items that you'll address if you have time, and
 items that can wait until the next revision.) Finally,
 conclude with some sort of reward for yourself and your
 teammates... you've earned it!

 Several folks suggested JoAnn Hackos' book "Managing Your
 Documentation Project" (John Wiley and Sons), which has
 also been highly recommended in various reviews. The
 skeleton that I've presented in this summary is well
 enough clad for the purposes of modesty, but the bones are
 still plainly visible in places. JoAnn's book should
 provide the necessary fig leaves.

 Thanks to the following individuals for contributing
 invaluable advice: Art Elser, Sue Gallagher, Bonni Graham,
 Sue Heim, Donna Menk, Robbie Rupel, Emily M. Skarzenski,
 Bill Sullivan, Chris Thiessen. Many other list members have
 provided information on related points over the past
 several months; thanks to all of you too!

 --Geoff Hart    @8^{)}
 geoff-h -at- mtl -dot- feric -dot- ca

 Disclaimer: If I didn't commit it in print in one of our
 reports, it don't represent FERIC's opinion.