Monday, April 30, 2007

Just-in-time wiki

The April 18 STC Chicago meeting was on Just-in-Time Documentation and Training with guest speakers Jacqueline Napier and David Orr. The PowerPoint slides can be found on the wiki that we created during the meeting ( as an exercise in collaborative development.

Jacque and David will post new materials on the topic as they become available. Feel free to apply to be a Writer so that you can add comments and information. If you sign up to the wiki, you can also invite associates who might be interested in the topic.


  1. Jacque and David had a lot of thought-provoking ideas. Two thoughts have been going through my mind since the meeting....First, I want to create a job aid to take on projects to remind myself to ask for all the possible artifacts that might offer reuse. On a current project that is almost complete, I just found out that the software is a rewrite of another piece of software for which the company couldn't get the source code. A developer told me that "about 75%" of the functionality in the new software, which I've just documented from scratch, is identical to the older software. While I looked at manuals for competitor products, I didn't think to ask about whether the software had a previous life, complete with a manual!

    Second, how does "good enough" come into play if the client thinks the doc is "good enough" without reviewing it? We need to give the client what they want, on the schedule they set, but what if that means that they don't have time for review?


  2. In response to your first question, I'd start near the end of the project lifecycle and request the test scripts, which should be walking the tester through the product functions at a step-by-step level. Ideally, test scripts should feed into the documentation process. If the test scripts aren't available, take another step backwards in the lifecycle and look at process maps and requirements documents. Those will at least give you an idea of what the user should be doing, when, and how.

    I've also learned not to underestimate the ingenuity of sales engineers and account managers. When formal demos and training materials don't exist for customers, SEs and AMs tend to create their own--they just don't tell anyone because they don't want to "get stuck" doing training and documentation for everyone else. If you can find out how end users are being trained and who is training them, you may find training materials with reusable content.

    On the second point, if the client doesn't have time for an acceptance review, I don't see what choice you have but to protect yourself. Perhaps they would make time for a one-hour walkthrough during lunch that would give both of you some degree of comfort, and at the end, they can complete the sign-off.

    If that idea doesn't fly, then I'd suggest amending the sign-off to indicate they are accepting the document as-is, without the final review. If there was a project plan or statement of work requiring the final review, then you might need to address that with them--it may be as simple as amending the SOW to exclude the term or adding a statement in the sign-off that the client's acceptance indicates the project is complete, whether or not all terms in SOW were met (or something more diplomatic than that).


STC Chicago Announcements

STC Chicago

STC Blog

Society for Technical Communication