Working with the developers

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

 Misti Delaney asked for tips on becoming part of the
 development team. Some time back, I asked techwr-l for help
 in imposing a structure on my employer's current chaotic
 process for producing documentation for upcoming software.
 (No, we're not there just yet, but Management was impressed
 that such structure could actually exist!) Here's what we
 came up with (hope it serves as a good starting point):

 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.

 If the product is still changing rapidly when you must
 start work, begin by planning and structuring based on your
 audience analysis, not by writing. Plan to fill in details
 as they become stable.

 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, Richard Mateosian, 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: Speaking for myself, not FERIC.