Building an onion

When I approach a doc set that needs a lot of work, I think of my job as building an onion. That is, creating successive layers of quality. As I build my layers I learn the doc set and the product, making the next stages possible.

The first layer is typically the result of a copy edit: remove typos and grammatical errors.

Next, work on consistency. Start to revise terminology and wording conventions (and build up a style guide). Ensure the writing is active voice, second person, present tense. Read the doc critically, thinking about the suitability of the content for the target reader.

At this stage research is required: talk to managers, product managers, developers, customer support, and customers. Look at how competitors handle similar areas. Read Wikipedia articles for background. Read the standards that your product is based on. Read analyst research for your market. And so on.

Revisit your terminology decisions, and start to formulate a clear picture of your target readers.

Create a list of problem areas in the doc set. Prioritize them.

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.

Thinking about writers

Being a good tech writer requires a lot of smarts and a lot of finesse. It's not just about knowing the authoring tools, learning the product, and knowing how to write.

It's understanding users, corporate priorities and the market.

It's learning which SMEs you can trust and which require double checking. It's learning how to motivate SMEs to help. It's learning how to work within other people's busy deadlines, to know when to push and when to hold back.

It's having the humility to accept other people's edits and the chutzpah to refuse other people's edits. It's having the tenacity to keep plugging away at something till you get it right, even though that process spans releases.

At your average tech writing job, it takes two years to become an expert in the product and customer base, form the necessary relationships, and learn the doc set. It is therefore important for companies to retain tech writers and to nurture them. Nurturing them means training, but it also means helping writers become more comfortable with responsibility - with honing and trusting their instincts.

All the supervision, editing and approval processes in the world won't make up for low quality writing. Unfortunately, all too often what holds writers back is all the supervision, editing and approval processes.

Writers have to "own" their areas of responsibility. Some writers won't do as good a job as others, but with time, training and nurturing, they'll get better. If possible, writers should see direct user feedback on their writing. Writers need to learn to have the reader perspective sitting in the back of their mind at all times. Every decision on terminology, wording, which information to include, topic length, and every other little thing should be made while thinking about the reader.

Some DITA CMSs include workflows that take doc ownership away from writers. I once had an editor who told me that our workflow was like a relay race - I as writer had prepared the first draft but then must pass the baton on to others. The editor didn't know anything about my users, the product or the market, and some of her edits created inaccuracies, but I had to fight for control of my content. That's the wrong way to operate.

Editors and information architects should not take responsibility away from writers. They can set guidelines and they can provide consulting services, but a writer has to be the expert in their own area. Otherwise it's just garbage in, garbage out.

Wait, you may say, what about hardware reference documentation that's essentially a list of specs? Well okay, there's an extreme end of publications that isn't really writing at all. But with tech writing, no matter how structured topics are or how complex a CMS is, at one end you have a writer and at the other end you have a reader. All the rest is secondary.