Journals by RSS
Journals by EmailThe 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.
We went happily along with the help as the main documentation until the second project, when we introduced finance functionality to the software. The customer from the finance end of things had some experience supporting the offices, and he suggested providing one- or two-page sheets that provided screenshots and callouts to guide financial secretaries through their main tasks in the system. The user education team had recently begun developing quick reference guides, and that’s what this customer’s request sounded like to me. So I created a collection of guides.
About this same time, having these archived WebEx sessions led to the concept of having short videos in addition to the quick reference guides. I created a number of Captivate videos and got customer sign-off, and the interaction designer put together a training page in the application. The page contains links to the guides and videos.
During the rollout, the two people managing the process asked for release notes, so I started doing those as well. We sent the notes out as a PDF by email. I later incorporated the timeless information (as opposed to release-specific) in the help system.
Over time, as we completed the rollout, we abandoned the WebEx recordings. This was necessitated partly by the organization’s switch to other technology for webinars.
Users started asking for message boards or forums where staff from different offices could talk to each other. Our product manager talked to the project manager about it, and he in turn talked to me. I began some exploration of platforms for wikis, forums, and even blogging, all in one if possible.
How We Should Have Done It
Looking back, it’s easy to see that this approach wasn’t very unified. Various customers gave input on the documentation as we went, resulting in an ever-growing doc set, instead of getting everyone together and deciding on a documentation framework at the outset.
Even better, I should have spent some time with users prior to beginning the first project. I’m developing a mental model of how to do audience analysis before planning a doc project:
- Observe users. If the product is new, observe users spending time with a similar product. For example, if you’re going to be working on a Web application, watch people use websites or web apps. If the product is the next version of an existing product, watch users interact with the previous version.
- Make notes of the questions they ask, the places they express frustration, how they interact with the product in general, and how they may try to get assistance
.
If I had done this early on, I would have been able to put together a better approach. As it is, I may be able to fix it.
A Second Chance
This concept of a support site is opening the door to making a more unified user assistance and training experience. The project manager has said that the editing of a wiki would be limited to me, the product manager, and the support staff in his department, not by the end users. The forum would be the main feature of the support site.
However, having this site would give me the opportunity to restructure the documentation and training so it’s housed in one place. Right now, the help system is accessed via a Help link in the header, and the quick reference guides and videos are opened from a separate page. A forum would likely be opened from a third link on the main page. So it’s pretty scattered now. Having a wiki with deliverables stored outside the application code would give me the ability to update help as needed, especially if approvals aren’t on schedule.
I’m somewhat relieved that I have this opportunity to rethink everything. Nothing is really going away; we’d still have help, PDFs, and videos, as well as release notes outside everything, but I have the chance to figure out a more unified presentation, and how to work the forums in with that. So even though this house has add-ons and expansions, this is a chance to change its face so that at least it looks like each part is supposed to be there.
Related posts (auto-generated):
- The Result of Working with the Stakeholders on Our Training Scheme
- Quick Reference, Videos, and FAQ in Front; Help in the Back
- Follow-up: A Skill for the Extroverted Technical Communicator
- Spending Time with Users to Learn How They Want Assistance
- Try a Quick Reference Guide for Short-Term Documentation Needs
2 Comments to 'A Little Thing Called Documentation Sprawl'
May 4, 2010
It sounds like a great chance make your very diverse coc types more accessible to your products’ audience. It’s the kind of chance more of us would like to have to reorganize documentation that has sprawled out as a set of products grew and evolved. Putting a new “front entry” on the whole structure sounds like a great approach to me.
May 6, 2010
I like the term “documentation sprawl” and the metaphor it evokes. I’m glad that a second chance came along so quickly, and that you’re making the most of it. From now on, whenever you start a new project, you’ll know what questions to ask at the very outset.