Categories
Business Marketing Process Rants ROI Training Uncategorized Writing

How to Improve Documentation

Recently, a prospect called us about a training guide he needed written for a new enterprise application his company had recently purchased and was trying to implement. Unfortunately, he had already paid the company that developed the application to create training materials but found, once he had a chance to review the materials, that they were not only impenetrable and useless from a user’s point of view but mostly incorrect as well. A complete waste of money. Alas.

When we met to discuss his actual needs, he said that he could probably write the materials he needed in a week or so but didn’t have time. So he was reaching out to us – professionals (his words) – for help. An excellent start to our discussions, I thought. Then he said he wanted the document written in Word. Not my first choice (see http://www.shoap.com/no-more-words-in-word-please) but it was clear this point was not negotiable. So we would write the document in Word. Ugh!

Once we had a chance to look closely at the actual application, it was pretty clear to us that we’d need closer to three weeks to document all the functions the client had identified. The problem, as we explained, was that to see how the application worked, we had to use it. And to use it, we had to generate the data and perform the functions before we could start capturing screens and writing step-by-step instructions. This part of the documentation process takes time; sometimes, unfortunately, more time than actually writing the steps on how to use the system.

To be fair, the client was very understanding. We worked through the list of functions and delivered the document he had asked for. And he was very appreciative (it took just under three weeks to finish document, by the way.). So in good corporate parlance, it was a Win-Win: He got the document he wanted and we got paid to write it. Was it the document he needed? Probably not. But as with which tool to use to write the document, when I questioned him on how he planned to use the materials he wanted created, he was quite adamant about what he wanted us to do and how we were supposed to do it. He was not interested in our recommendations – it was another non-negotiable item.

So I wondered, when this client was shopping for his new system, did he tell the developers how long it should take them to write the application? Did he tell them what language to use to write the application? What database? Probably not. And yet, when it came to creating the materials he needed to successfully implement this system, he had no doubt that he knew best how to go about it.

Most experienced technical writers have many years of experience working with a host of different companies on many different kinds of projects. From this experience, they learn what works, what doesn’t, and how best to approach and successfully complete a project. I look forward to the day that clients tap into this expertise and let us help them deliver useful documentation.

Leave a Reply

Your email address will not be published. Required fields are marked *