Technical Writing, Documentation, and Training

404-873-4288

Our Blog

Expert tips, advice, opinions, and viewpoints.

If, after examining and analyzing a problem, I find the best solution, I recommend and, at times, fight for that solution. This approach seems so self-evidently correct that I’m shocked to find myself even writing it.

How can this be, you might ask? Let me explain.

When we meet with a new client and determine that we are the right people for the job, the client always asks what technical writing tool we propose to use to write the technical material. It’s a fair question. As the technical writing experts, we should know the best approach to creating the materials. And we do.

Often, however, the best tool is not always the right tool. For example, a client recently approached us about rewriting the user manuals it provides with its products. The current manuals include both hardware and software instructions and were written in Microsoft Word.

There are several different models of the product, each one a slight variation on the other. Where one model may have two cassettes, another has four. But the way the machines work and how the software controls these machines is exactly the same. Currently, there is a separate manual for each model.

The downside of different manuals for each product, of course, is maintenance. Each time there is a software upgrade or a new component or feature, each document must be updated with exactly the same information. Making these updates is incredibly time-consuming, not to mention the multiple opportunities for making errors.

But what is there to do?

Simple. There are several technical writing tools that use a single-source of the document content but still produce documents that are customized for each of the different models. Such solutions are ideal for just this type of situation. So instead of maintaining five different documents, you only have to maintain one. Pretty slick. In the past, I would advocate strenuously for such a wise and efficient approach.

But this solution is only feasible if a) the client is willing to invest in purchasing the tool and training someone to master it, or b) the client is willing to rely on a third party (our company hopefully) to maintain the documentation. What happens if the client wants to bring the documentation function back in house and discovers that it can’t update the manuals because no one knows how to use the tool and/or doesn’t have a license for it?

As Hamlet says, “there’s the rub.”

Providing a document the client can’t update is obviously not efficient or wise. So part of our “discovery” process now is to determine up front how the client will update the documentation.

View More Posts by: jeffrey

Leave a Reply