Sunday, November 18, 2012

Continuous improvement

In my many years as a tech writer, I have seen a lot of truly awful docs. The reason was almost always the same: the doc was needed in a rush, and then nobody ever went back to make it better.

Even with well-planned, carefully written and edited docs, there should always be a process of improvement. All too often there isn't. Worse, groups that have CMSs often have highly-prescribed workflows that completely omit the need to tweak the doc after it is released. The assumption is that once released, the doc is finished. Perhaps they also worry that the company will incur higher translation costs if writers are allowed to polish published topics. But the way I see that kind of workflow is this: the workflow accounts for everything but quality. If it's a highly-prescribed workflow, you have pretty well ensured that you won't get quality.

Why should docs be revisited and continually improved? Many reasons.

Writers are continually learning new things about the product, technology, users, and how everything fits together. Frequently, we don't really get it when we write the first version of a doc, even though we think we do at the time.

Also, things change. When you wrote that you recommend Flash v9, that was correct, but now Flash v11 is out, and you need to change the wording to "Flash v9 and later" - or whatever is the case. When you explained what a Ribbon is in a UI, ribbons were new, but now we've all migrated to Office 2007 or later and we don't need those long explanations in every task (are you listening, Madcap?). When your product first came out, Product Management wanted to focus on a certain module, but now the focus has changed. And so on.

There are always errors. It's inevitable. We can't ever assume that the docs are absolutely correct and complete - we should periodically be checking them, and preferably do a thorough review every so often. Readers notice when the same error persists in release after release, and it doesn't give them much faith in your company.

Finally, it is difficult to be fully objective while writing something. Going back with a fresh eye will always result in seeing things that could be said better.

There is a sentiment that I see in a lot of doc managers, writers and blogs that quality isn't all that important. All too often, doc departments prioritize things that don't matter one iota to their readers. But content is king: helpful content and good enough navigation that readers can find the content.