Edit heavily or rewrite from scratch?

December 12, 2008

On a technical writers’ email discussion list in August 2008, Diane asked:

I have not created online help. Now I am tasked with this project.  I know a little HTML and I am learning about the application. This is [a military] project. HTML Help is already written, but it was written by several people who are not writers, includes help that is not helpful, and it’s a mess. They want me to redo it. The online Help already exists, but some of the writing is bad… that’s easy to fix. Some Help explanations are ‘See Danny’.

The problem is that the Help is HTML Help and I suspect that it was not done with any tool. These are developers who wrote it and it has many voices. If they hard coded it, could I make changes to it by using RoboHelp? I have RoboHelp 2002 here. I would have to install it. I just don’t want to break what’s already there.

My response:

I’d be very hesitant about installing such an old piece of software as RoboHelp 2002. Also, it’s unlikely to be compatible with Vista (if you have Vista installed).

If the writing is that bad, then you have to decide whether it’s going to be quicker to edit it, or to start from scratch.

I’ve been in that situation—it was quicker to start again from scratch. You get one voice, and you don’t have to spend your time trying to figure out what someone was saying, or finding Danny who left the company 3 years ago!

However, before you make that decision, do some metrics to ‘prove’ to your boss and yourself that starting from scratch is a better option.

What I did was take a topic that was reasonably generic—one where I didn’t have to have much/any knowledge of the product.

I then created that topic from new and timed myself. Next, I timed how long it took to edit the original, then make the corrections in the source document. I used those times to justify starting from scratch. For example, let’s say it took 10 minutes to write the topic and 30 minutes to edit and make the corrections. Based on the times you recorded, you could have a case for stating that it would take three times as long to edit and correct than write from new.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: