When Trust Becomes a Characteristic Flaw in a Project

by Tom Johnson on Dec 11, 2008
categories: technical-writing

In tech comm, you often have three layers of clients: (1) the project manager, (2) the business department sponsoring the project, and (3) the actual end users who will be using the system you're developing.

In most places I've worked, the project manager (PM) has been wary of me interacting with people beyond level one. The PMs usually see it as their job (or the business analyst's job) to gather the customer's requirements, to analyze business needs and technology solutions, and to interface with the clients and see if their needs are being met.

If you're the technical writer, the PM might imply something like, "Your job, technical writer, is to merely write the documentation. The business analyst and I, as well as the engineers on the project team, know how the system works backwards and forwards. Any questions you have about the system, we can answer. Don't contact the sponsoring department or end users -- they're very busy people. We meet with them regularly, so any questions you have can be directed through us."

I assume it's because of my blind trust that I get sucked into this myth. Joe Sokohl tried to shake me out of it last year at Doc Train with his presentation on changing the rules of the game to benefit the end user. I even interviewed Joe for a follow-up podcast, nodding in agreement with each sentence he spoke.

Since I failed to implement his advice, it should have come as no surprise to me the other day when, upon near completion of a project, the end user handed me a 135 internal procedures manual referencing a number of tasks that I failed to include in the documentation.

The internal procedures manual would have been a goldmine in writing the documentation. Its existence came as a complete surprise to the project manager, program manager, and quality engineer, all in the same room. No one had any idea such a document existed. Had I met one-on-one with the end user earlier in the project, this document would probably have come up in the first five minutes of our conversation.

For the next two days I read the internal procedures manual, almost kicking myself every few minutes. Had I begun with this, I said to myself, I could have created a help system that better matched the user's processes and tasks, better aligned with their needs, and more thoroughly employed their vocabulary and conceptual organization. Instead I had struggled for months without it, navigating my documentation ship with only the QA engineer at the lookout.

I had a similar experience at another company, only with worse consequences. We were implementing an enterprise-wide content management system. The entire 77,000 HTML pages of the previous intranet had to be manually migrated to the new system. The new system provided a comprehensive taxonomy that would restructure the content into logical units based on knowledge domains, rather than specific departments.

My job was to walk users through the migration process and introduce them to the new system. On more than one occasion, I asked the business analyst how users would find content in the new system. "Oh, they'll know. The navigation is organized logically by topic. Each department will know where to go because they're familiar with these knowledge domains," she said.

As you can imagine, when the content management system was rolled out, users couldn't find anything. Because the system was sluggish, looking in the wrong place meant waiting and waiting for pages to load. The users complained and resisted. I often thought of the business analyst's words, "Oh, they'll know." Oh, they'll know all right.

As hard as it may seem, lesson one of technical writing is to break the rules and contact the end user. Conduct a mini-ethnography. Sit with the users. Call them on the phone. Send them emails. Do not let it get to the point where you feel you must go through the PM to communicate with the end user. As hard and uncomfortable as it may be, the consequences of not talking to the end user can be crippling to your help.

If you're isolated from the end user, your documentation may not fit the user's processes, vocabulary, or tasks. Your documentation may be in the wrong format (for example, PDF instead of video). The PM and business analyst may have pointed you in the right direction, but their knowledge is incomplete, since they too are outsiders. They don't interface with the end user with the same perspective as a writer. They don't work in the users' department. They don't do the users' tasks on a daily basis.

But on a deeper level, you must get in the users' heads for another reason. You're not so much documenting how a system works, but how a certain group of people will use the system. And how they use the system depends on how they think, the daily tasks they're trying to complete, and how they describe and organize those tasks in their heads. You can't know that information unless you get inside their heads.

I recently heard a Jewish parable that I think describes this situation well. A child was scared of jumping, so his mother set him on the stairwell -- just one stair up -- and said, "Jump." She caught him on the landing. Then she told him to jump off the second stair, and then the third, and fourth, until the boy's confidence grew.

Each time, the mother caught the boy on the landing. Eventually the mother told the boy to jump off one of the highest stairs. The boy, filled with newfound confidence in his jump, gladly did so, but as he jumped, he watched in horror as his mother stepped back and let him crash on the floor, bruising and bloodying himself. When the crying boy finally pulled himself up, he heard his mother say, "That'll teach you."

In the parable, you and I are the boy. The mother is the project manager or business analyst, providing safe little answers to our questions. Just when we feel confidence with the project manager or business analyst and place our full trust in him or her to help us land safely, he or she figuratively moves to the side and lets us crash to the ground. Reality unfolds, and when we pull ourselves up from the ground, bloody and bruised, we're staring at a 135 page internal procedures manual written by users.