The 101 Faces of Documentation


Note: The first part of this post was published last week. Please click here to read it, if you haven’t already.


The CEO stared at the candidate for publications manager. Outfitted in black from head to toe, it appeared the interview was his first stop after a funeral. The executive asked the man to repeat himself, because what he previously said didn’t quite register.

“Sure,” the thin figure replied obligingly. “Documentation is dead. People like me killed it.”

What the heck was HR thinking? The CEO didn’t know if he should call a cop or suggest the man consider a career as an undertaker. Talking to these creative types was often a waste of time. This case seemed not to be an exception.

The prospect cleared his throat. “Okay. So I was being dramatic. What I really meant was documentation as we know it is dead.”

The CEO frowned.

“Hey, the lady in HR thought it was interesting! I’m here, aren’t I?”

The visitor’s winning demeanor was such that the executive couldn’t help but give him the benefit of the doubt—for a few more minutes, at least. “Go on,” he said.

The man adjusted himself in the chair as if he were hunkering down for the long haul. “One of the reasons people think that documentation is ineffective is because . . . it is!”

Score one point for the applicant, the executive thought. This guy wasn’t going to blame the user or go into some long-winded tirade about the post-literate society.

“I’m listening,” the CEO replied.


“You have to meet the learner where they’re at,” the visitor continued, “especially when it comes to technology. Not only do people learn different ways, their training needs change from situation to situation. The best software companies deliver information in as many channels as possible to make sure all bases are covered.

“In my opinion, you should start with a set of user manuals, written reference points that contain all the information about product use that’s important to know. It’s a foundation. But just like people in a house don’t live in a basement, learners don’t want to reference the source all the time. So you take the information and transform it into the outputs your users need.

“For example, you can take the material in the manual and cut it up into digestible chunks accessed from the software with a click of a button. That way the user sees only the information relating to what’s in front of them. There are companies that provide software making it easy to convert and reorganize a manual’s information with a minimum of effort, so the writer doesn’t have to re-type the text from the manual to the online help system.

“For the more visually oriented, you can offer video training. The advent of desktop video tools have made this more practical than ever, and robust web platforms allow you to offer these tools right on site. In fact, if you design your website with the right content, a user can learn from it, too.

“But some people like to learn by doing, and for people like this, other methods may be more effective. Classroom instruction, guided online training with a live auditory/visual link to the teacher, or even phone-based instruction are a few examples.

“I’m just scratching the surface, really. There are literally 101 forms of user documentation, some of which don’t look much like documentation at all.”


“So if you’re a writer, doesn’t this stuff scare you?” the CEO asked. “Sounds like you’re talking yourself out of a job to me.”

“If I was a lousy writer, maybe, or even worse, an inflexible one, unwilling to change,” the candidate replied. “It isn’t the strongest that survive; it’s those who are most adaptable. Most forms of communication—for sure the ones we’ve just talked about, whether it’s a video script or a training syllabus—start with writing. Can’t get away from it, really. Maybe all those liberal arts majors are going to have the last laugh after all—that is, if they’re adaptable enough.”

The CEO pondered this, and shut his eyes. When he opened them, the dark figure was gone, a wisp of something akin to smoke hanging in the air where once he sat.

This had a dizzying effect on the CEO, but he managed to gather himself and get on the line with HR. The department manager insisted no one had been sent up. It surprised the executive less than you might think, given what he had just seen.

He put down the phone and pondered what he had heard, mildly amazed that what he had considered to be a necessary evil suddenly seemed compelling and maybe just a little more important than he had originally thought.

He got back on the phone with HR.

“I have a request,” he said. “From now on I want to be a little bit more involved in hiring the creative staff. It’s sudden, I know, but I’m pretty sure I know what I’m looking for in a candidate. Just don’t ask how I know.”

Leave a Reply

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