Why ‘find and replace’ doesn’t work for documentation

I’ve been having a discussion today about a ‘behavior’ with some writers that annoys me. Situations often crop up with our documentation where a term or other phrase within the docs needs to be replaced with a different term or phrase. This usually occurs because of an update – something in the software changed name or version, or where differences occur between a different product or platform with a shared source. A feature or a defect might specify that x needs to be changed to y.

On the surface this kind of thing looks like an easy fix. OK, no problem, I’ll go and do a search and replace. I’ll search for x and do a direct replace to Y. In fact this is so easy, I’ll open my topics one by one, and fill in a dialog box in my editor with the thing I want to change with the other thing I want to replace it with and click Replace All. Or if I’m really clever I might write a script to replace all those occurrences in all my files. Terrific.

Well actually no. Not terrific. Doing a find and replace like that is not a good thing. It might be quick and simple. But watch the quality of your hard written docs go in a downwards direct. When you write something you consider context. The stuff you are writing makes sense and is accurate. When you start replacing words with something else without actually reading it, it won’t make sense anymore. These words won’t necessarily work in the context of the other words around them. If you do a find and replace, how can you know that you are replacing the right things, and not accidentally changing things you didn’t intend to. Or missing subtle differences that you should have found? Most key is the fact that you lose the flow and the context, and the information may now be wrong or not make sense. This is obviously bad news for your users. Yes, you might have saved some time, but you’re going to spend more time later unpicking the holes because you don’t know what you’ve changed!

What’s a good way to approach to dealing with find and replace type requests then? Well, and this of course is my own opinion – I think that the search aspect is useful – look for the terms or phrases that you need to change, and then read the docs around each of those occurrences to ensure that what you want to change it to still fits, makes sense and is correct. Check it actually does need changing. And if the words around it need to be changed. Maybe you need more information, less information or a different set of words? Go through each one, and at least skim read those topics that are related to see if there are similar but not the same terms or phrases used, so that you can check these should be changed or left as they are. Why bother? Because it keeps quality high and ensures that the docs are accurate and useful as possible for the user.


Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

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

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s