The Case of the Stolen Documentation

by Tom Johnson on Jan 6, 2010
categories: technical-writing

Some months ago I created a half a dozen quick reference guides for an application that would have a potential audience of thousands of users (after it cleared the beta phase). The size of the audience gave me hope that I would actually create documentation to be used by more than a handful of people outside the internal workings of my organization.

I created the guides in Adobe InDesign because it seemed to make sense for the situation -- the application was relatively simple, and there were just a few roles. I crafted the layout and design carefully, branding the guides with the same color and feel as the application. I meticulously ensured each task was described with concision and accuracy, and I limited the text for each guide to one double-sided page to avoid intimidating the users. During each application update, I reviewed the guides against the new use cases and updates and made sure the instructions matched the new functionality.

As you know, I've given several presentations about quick reference guides and have written about them numerous times on my site, even calling quick reference guides the poetry of technical writing. These six guides were my poems. I felt a sense of pride with them and displayed them in my gallery of quick reference layouts and during team meetings.

And then one day, I received a phone call. One of the clients asked for the source files so she could update them herself (or have other designers update the source files under her department's supervision).

The source files? I said. They're in Adobe InDesign.

Yes, please send the originals, she said. I felt a bit offended. No one ever asked me for source files before. I wondered what it was she wanted to update that I couldn't do. Wasn't I close to the engineers and project managers, and therefore in a better position to update the documentation? Wasn't I keeping it all up to date?

But I know I work for an organization, and the products I make don't belong to me. So I zipped them up and clicked Send. For a long time, that was the last I ever saw of them.

I hung around a couple of project meetings after that, but it was clear that the documentation was now owned by someone else. I was no longer needed. Okay, I said, and moved on to other projects.

For a couple of weeks I felt upset and confused. I didn't know if I should periodically inspect their updates, if I should close the project entirely, or what. I laid low and continued to work on other projects.

No more emails, no more requests, no more maintenance. It felt as if my documentation was stolen.

It wasn't until nearly three months later when I finally received another phone call, this time of a different nature.

Who Owns Your Documentation?

Stolen documentation isn't a unique experience. It happens to technical writers everywhere. It's more a question of documentation ownership rather than theft. Ben Minson explains,

One of technical writers' worst nightmares could be for a non-writer to come along behind and not keep up the level of quality we established in a documentation project. It scares us in a sense to be replaced by non-writers. (Who Will Maintain Your Documentation?)

The fear is two-fold. On the one hand, the non-writer who takes over the documentation can act like a bull in a China closet, copying and pasting from Word, mixing styles, not understanding the setup, basically wrecking the consistency, the bullet levels, the formatting. If you see the documentation later and find that the client has added steps without numbers, included text that breaks every rule in the style guide, won't that be unnerving? Yes, it will make you want to jump out the window.

Worse, though, is the thought that your work products can be maintained by people with no writing skills at all -- just regular people, perhaps secretaries or interns or project managers. This devalues the technical writer's expertise and talent. If enough projects follow a similar route, won't you eventually be left without any work?

Advantages of Having a Person on the Inside

Scott Nesbitt also comments on document ownership. He says, "Technical writers can be … well, control freaks. We don't like other people messing about with our documentation." Of course anyone who spends hours proofreading the same chunk of text -- changing semicolons to commas and then back to semicolons, with an eye for language precision that borders a psychological disorder -- is going to feel threatened when someone takes over the content. (I've always hated group work.)

But Scott also points out a more important matter. He says,

Something that we need to remember, though, is that it isn't our documentation. We're not writing it for ourselves. We're writing it for the people using the software and hardware that we're documenting. And, as I keep saying, the insights of users are just as valuable as our own. (Getting Users to Read the Documentation)

When you look at the situation from the vantage point of who has the right information, it isn't always the technical writer. While the writer may be close to project team, the writer is an outsider to the business processes of a department, to the constantly changing workflows and needs of the users. Having a person on the inside, i.e., in the department that interacts with the users, can be an incredible asset to keeping documentation relevant and up to date.

Reactions from the Twittersphere

I polled the Twittersphere to find out how common this sort of situation is, where you create documentation that is later owned by the client. (And by client, I don't mean the end users, but rather the sponsoring business department for the project.)

Kirsty Taylor says it's "very common." She even creates her documentation to be "highly customizable" so that clients can easily modify it. Pancho Castano says his clients frequently want to own the documentation, "but not only that: they also create it in the first place." In other words, the clients collaborate in the initial authoring process as well.

Tjrainey says resellers definitely want to own documentation, but not mainstream users. Mike Starr says "multiple clients want to maintain documents" after he finishes. He provides all the information they need to maintain it but frequently need his help.

Joe Sokol says "clients almost always want to own the documentation," but notes that the users don't necessarily want ownership. Aaron Toronto says maintaining single control over documentation "is outdated in this collaborative age."

Shelton Oliver has clients who want to own the documentation, "and several who want to rebrand/respin the doc for their company, usually for training." Alan Houser says having clients own the documentation is "a very common requirement/request. And challenging to provide."

Scott Nesbitt says clients want to own the documentation "probably more often than we realize." Wordtree says the request is "very common when there is no formal documentation team," and Arroxane agrees. Rahel Bailie says clients want to own the documentation "99% of the time."

The responses are overwhelmingly positive about clients wanting to own the documentation. Obviously companies who hire consultants to create documentation would want to own the documentation after the consultant finishes. But I'm seeing the trend within companies as well. When the company is sizable enough to have numerous business departments, those departments outside of IT often want ownership of the documentation.

Turning the Corner on Client Ownership

After I had my documentation theft experience, I started to prepare proactively for similar situations. I realized more of the advantages of having clients maintain the documentation themselves. In addition to being close to user needs and processes, having clients own the documentation also lightens my project load. This is an important point, not just a matter of laziness. The longer you work for a company, the more projects stack up. Minson says,

As time goes on, if you're maintaining the documentation yourself but you're also taking on other projects, you can end up with an extensive vault of projects to maintain. You may start to be pulled in many different directions.

The more projects you finish, the more projects you have to maintain. Pretty soon you're being pulled in twenty directions at once and you don't have any time to write new documentation, because you're making small updates here and there. Though the updates are minimal, you have to understand all the implications of one update in the context of all the other content.

In my situation, I'm one of eight technical writers in an organization of 5,000 plus employees, with an IT department of about 600 IT professionals. I want to spread out my talents as far as possible. I'd rather write documentation for 17 different departments and have it poorly maintained than only stick with 3 or 4 projects and maintain them all myself. It's a matter of influence. You can keep a tight hold of several rocks in your hand, or a loose hold of a dozen.

Directions Toward Collaborative Authoring

Collaborative authoring doesn't extend only to pre-release writing. That mindset is founded on the assumption that documentation is finished once the software is released. In reality, collaborative authoring includes authoring both before and after the software is released. Before because you want to ensure the documentation is as accurate and complete as you can before releasing the software. After because inevitably you'll run into gaps, user questions, quirks and bugs, and other tasks needing explanation that you didn't anticipate before the release.

If you're stuck with costly proprietary tools that require local installation and training to understand, your attempts at collaborative authoring may end up like the experience I described earlier, where your source files are suddenly "stolen."

But I only had to give away the source files because the platform for documentation (Adobe InDesign) didn't allow for collaborative authoring. In order for the business department to collaborate in the authoring process, they had to "steal" the files. The InDesign platform falls under the old paradigm of a one-author, one-tool workflow.

After they took the source files, I adopted a new platform for my projects: a wiki platform based on Mediawiki. (Don't criticize my choice of wikis; it's merely the allowed wiki platform for my organization.)

With a wiki, I can collaborate before and after the release. Clients don't have to take the source files from me to contribute, and I don't have to wash my hands of the project when they take away my files. I can keep tabs on the updates, with automated notification emails sent to me each time the client makes a change. And I can massage their modifications, keeping the style consistent and professional. Updating it is as easy as clicking the Edit button, because it's all online, accessible from any browser, and tracked with version history. (At least that's the theory. My head is still in the wiki clouds here.)

Months Later

A couple of months later, I finally received another phone call about the documentation. This time one of the clients asked for some helping updating a web page I had created. They needed new thumbnails and updates to the web text. They also sent me the updated quick reference guides at my request.

To my surprise, it looked good. Totally different, but well-designed, clean, and visually appealing. The authors had elaborated on the written text in numerous places, adding context to make the tasks clearer. I realized that in my desire to fit the instructions on one page, I had taken too much out. But clearly my documentation was still the foundation.

Some decisions confused me, such as the removal of screenshots and images, but overall the effect was similar to loaning my car out to a friend, and instead of getting it back trashed, with dings on the side, and on empty, I received it back tuned up, detailed, and with a full tank.

From my college days, I remember reading a literary critic named Mikhail Bakhtin. Bakhtin argued that diglossia -- the presence of more than one voice in a text -- is partly what makes the text interesting.

I think the same could be said of technical writing. When multiple writers add their edits to documentation, looking at it from different perspectives and situations, the effect is greater than one author alone can achieve. In this sense, even if you lose your source files, documentation is never stolen, only strengthened.