My Journey To and From Wikis: Why I Adopted Wikis, Why I Veered Away, and a New Model

by Tom Johnson on Jun 11, 2012
categories: wikis

PDF version

This is a story about my journey to wikis and back again.

The Need for Shared Ownership

Several years ago, I worked in a department that produced products for senior leadership in our organization. I was the only technical writer, one of the first hired as a technical writer in fact. I used Madcap Flare exclusively to create and publish documentation in the form of online help, PDFs, and quick reference guides. I also used Adobe InDesign to create more visual, one-page quick reference guides.

I remember one day early in my employment at the organization. I had produced the first double-sided quick reference guide for the department's flagship application. The department lead saw the guide and – according to reports related to me by others -- actually became teary-eyed he was so happy. He felt he'd found someone who finally got it, someone who could create short, visual documentation that got right to the point. Perfect for executives, as well as users.

His preference for short guides encouraged me to highlight this deliverable even more, and with another project, I pitched a series of quick reference guides for each role. These guides would actually stand alone, without relying on online help as a supplement.

I meticulously created the layout and design, matching the look and feel of the application with a craftsman's eye. The guides were works of beauty. At first I produced just four guides, one for each role, but soon I needed a couple more – an overview, and a process summary.

I handed off the PDFs to the product manager to distribute. I attended rollout pilots with user groups and watched users interact with the documentation. I refined the guides to perfection. And then one day, I got a call from a higher up office. They wanted me to send them the source files so they could own the content. No real explanation why, just a request.

Reluctantly, I packaged up the InDesign files and sent them off to the department. It was the last time I ever worked on the files. Not having the source files, I only occasionally would see a PDF from their department. They stripped out all screenshots, combined all the guides into one handbook, and changed the color scheme and typography significantly.

The application underwent additional iterations and updates. I always wondered who was updating the documentation, if at all. I was told it was being taken care of.

This experience of having documentation taken from me affected me profoundly.  I wrote about this experience in a post called, The Case of the Stolen Documentation. In many ways, I felt the other group “stole” my documentation. The project lead also felt that appropriating the source files wasn't right.

This experience persuaded me that I needed a more collaborative model for help authoring. With a collaborative model, users wouldn't need to steal documentation from me; instead, we could work together on updates. There would never come a day when someone would ask for the source files and then cut me out of the process. I could always have a hand in editing the content, and so could others. This was, after all, the era of Internet collaboration and web 2.0.

Next: 1.1 The Need for Constant Updates (Wikis)