Why Help Authoring Tools Will Fade

by Tom Johnson on Nov 25, 2009
categories: technical-writing • web-design

I read a blog post the other day that I can't stop thinking about. In the Myth of Single Sourcing, Michael Hiatt writes,

The main issue for me is between authoring static in-house documents using single-sourcing methods before publishing, or capturing information sources dynamically after publishing from online social networks, linked data sources, and knowledge mashups.

The myth of single-source authoring is that it actually has a life in the future and remains a viable goal for many information developers. With so many mega-trends against it—such as the belief that static authoring from a single vantage point from a single author paid by a single organization is a workable system—seems ludicrous. Instead, we should be looking to capture, sequence, and give context to the wealth of rich content already published in context from the Web. Collaborating with the many subject experts, authors, videographers, bloggers, tweeters, and writers coming together on the Web with shared interests will be powerful if it can be harnessed.

Michael undercuts the idea that you can create help from a single author working from a single perspective in a single point in the organization. To add to this scenario, usually that author is an outsider to both the environment and business processes he or she is documenting. Further, the author usually moves on to another project as soon as the software is released.

This morning I had a meeting downtown at SLC headquarters. I've become accustomed to wearing business casual clothes to work, but at headquarters, I have to wear a full suit because that's the dress code. In an early morning meeting, I listened to several department leads explain my new project. It would involve extensive knowledge of cataloging and archiving techniques, a robust off-the-shelf system that had been customized, five main divisions or modules to conquer, each with their own resource leads, about 200 constantly rotating users complementing a core group of specialists, and an aggressive time frame.

As I listened and glanced through the archiving and cataloging procedures (did you know there's a Society of American Archivists, and that they have in-depth protocols for how things should be done?), I realized that learning the business process surrounding the application would require complete immersion in each of the five divisions over the course of several months. I would need to constantly interview subject matter experts, participate in the actual archiving and cataloging processes, and make sure everything I created was reviewed, checked, and edited for accuracy by each of the five major subject matter experts. The end documentation would probably be several hundred pages for the initial release.

Keep in mind that I have about three other concurrent projects that I'm working on with approaching deadlines (unlike developers, no writer ever gets to work on just one project). Could I pull something together by February/March?

At this point, Michael's post was resonating like a blinking banner in my head. Authoring from a single vantage point from a single author is ... ludicrous.

Even if I were to import existing documents and materials from SMEs into a HAT, who would own it after I finished? Would I become a permanent installation in the department, constantly processing updates, verifying instructional clarity, addressing gaps and making edits? If not, would the documentation become stale six months after release, when SMEs decided to change their business processes?

In an organization where several thousand people have only a handful of actual technical writers, we're a scarce resource. I bounce from project to project, like a little visiting angel (or devil) who works a little documentation magic and then moves on.

Another group on my team is tackling an even larger project, one that involves complex financials. They're using Flare. They started using X-Edit and entitled a handful of business writers to contribute content with it, but X-Edit proved either too buggy or unworkable. Now the business SMEs are passing Word documents to the guys with Flare, who are inputting the information into the HAT. After release, the idea is to have the business department own the documentation and continue making updates using Flare. It will be interesting to see if they actually do it.

In thinking about these robust software scenarios, where products require extensive knowledge of business processes, have elaborate interfaces with hundreds of possible tasks, and are run by dozens of specialists constantly refining their own business processes, is there any other platform besides a wiki that can actually work? What else can you use to enable 10 different authors to make simultaneous updates, to maintain the documentation after the release? How else can you infuse the documentation with the intricacies of a department's business processes?

Using any of the standard authoring tools -- Flare, RoboHelp, Author-It, Doc-to-Help -- leaves you with the ridiculous model of a single author working from a single vantage point from a single organization trying to pull together an ocean of information. Because that model is untenable and unscalable, HATs will fade in favor of collaborative web-based authoring technologies.