Rebuilding existing documentation. I don’t know about you, but I find that to be something of a daunting proposition. Especially if I wasn’t the one who wrote the original.
Sometimes, though, this scary deed must be done. I’ve done it a few times, and it’s not easy. It can be done, but the process of rebuilding a piece of documentation can be on par with starting a new documentation project from scratch. Actually, in some cases it might be a bit more difficult.
Intrigued? Read on …
Why rebuild?
Documentation can be like an old home. On the outside, it may seem robust but inside there are problems. Some of the problems can arise from writers — haphazardly or not — updating and patching the documentation. In other cases, the work might be so poorly done that the documentation is useless in its current form and patching won’t help — it might make the document even worse, and definitely more difficult to maintain.
You might also be in a situation in which an application is being rewritten. If that’s the case, then the some or all of the current documentation becomes invalid.
Strategies to try
Two cases in which I had to rebuild documentation really stick in my memory. In one, I had to throw out the old manual and create a new one. In the other, I had to do a lot of tearing out and remodelling. Here are some of the strategies that I devised while working on those (and other) projects.
First, see what you can salvage from the old documentation. Reuse isn’t just a matter of sharing content across existing documents, but also repurposing it. That can save you a lot of effort in the long run. Sometimes, you can salvage quite a bit. At other times, you can recover only a little. Or none. In one case, I tried that and only reused two sentences. A small part of that was because the application was rewritten and much of the information in the old manual was invalid. But it was mainly because the old manual was badly written. It was less effort to write the content from scratch than to rework what was there.
Look at the content from the perspective of the audience and decided what you should and shouldn’t keep. Some technical communicators put everything into a user guide. Users don’t need everything. You’ll probably find that there’s a lot you can rip out. A couple of gigs back, I did this with a 900+ page guide. I sliced more than 50% of it out, and was able to consolidate a lot of repeated information in overview sections. I still had to rework and rewrite large chunks of that manual but my renovation work put the documentation on a more solid footing.
When ripping content out of an old guide, think about whether or not it can be reused elsewhere. In a previous post, I mentioned that you can take content that doesn’t really belong in user documentation and post it to a knowledge base.
Finally, don’t try to get into the head of the person who wrote the documentation. It’s only natural to think Why did you do that?, but it serves no purpose — other than to slow you down and bump up your levels of frustration.
Have you had to rebuild documentation? If so, share your experiences (good and bad) by leaving a comment.
Photo from http://www.sxc.hu