The software applications I’ve worked on for the last five years have been part of an effort to replace old desktop applications largely with Web-based applications with a central database. These new applications are more flexible in most areas. One application’s development has taken place in three one-year-long projects with some minor enhancement projects. We’ve rolled this application out to hundreds of offices worldwide.

The documentation strategy over the course of these development projects has, unfortunately, resembled a building with several add-ons rather than a single, unified structure—wings added, walls moved, different materials used. Where I live, no one builds like this, except in residential neighborhoods and on college campuses. This approach doesn’t exactly make for a consistent experience for users. It’s what I’d call documentation sprawl.

The Growth of the Documentation

Our documentation approach for the first project was a context-sensitive help system. The legacy application was context-sensitive because it was F1 help, and it also had a section of how-to topics. The product manager wanted a comparable help system and liked the one I’d just created for another project, so I set up the help with map IDs for the CSH topics, and I added a getting started section and a how-to section.

As we rolled the application out to a small number of offices for a beta period, we trained their staff via WebEx. Over time, as we trained more offices, we gathered up a collection of recorded training sessions. We kept a running list of the best sessions and their attributes so we could distribute the links as appropriate to other office staff.

› Continue reading…

Bookmark It

Hide Sites

This month we’re transitioning from an old custom document generation application to a new one. Having been the person responsible for training a small group of users, I spent much of yesterday with the person upon whom falls many of the weekly tasks. The project team and our customers wanted to be sure that she’s ready to go when we’re live with the new application and the old one is turned off. (The old one is connected to a legacy database that will be retired soon, so it won’t be available as a backup for very long.)

As we went through the document generation process, this particular user—let’s call her Melissa—let me know where she wasn’t clear on one thing or another. Particularly, she wasn’t clear on what were the exact differences between each of the three screens that the process involves. As we got to the end and Melissa still seemed a little fuzzy, I asked, “Would it be helpful to have a one-page guide that walks through the three basic steps?”

Now, there is a help system. I even have a topic that covers this process from start to finish, involving about ten main steps. However, I could suddenly visualize a page where I matched three steps (with a few substeps each) with the three screens. But the approach here was to give the instructions in their most basic form and leave out a bunch of the details.

› Continue reading…

Bookmark It

Hide Sites