When you say documentation (part 1)

Several years ago, my team wrapped up phase 2 of a big project. We had been working feverishly on upgrading or replacing some old fragile systems at work. The systems had numerous problems and everyone was getting buried by support calls and complaints. We couldn’t get any peace until they were fixed. So, to speed things up, we focused primarily on getting results (via sw fixes and infrastructure upgrades). User docs were not anywhere on our radar for this project.

After we completed phase 2, things were working MUCH better. Support ticket flow was down 80% for the systems that we fixed/upgraded. It was a huge success. One month later, we cut that number in half again. However, instead of thanking us for fixing the systems, the support team complained because we obsoleted their documentation. “What were they supposed to do now, when a system went down?”. I was thinking “buy a lottery ticket, because you are talking about an unusual event from now on”. I knew they were not in the mood for a clever joke. So instead, I explained that if a system went down, we would seek the root-cause of the problem and fix it. Then that problem would be solved and we would never see it again. No more calls.

This answer did not seem very satisfying to the support staff. They wanted documentation. They believed that they could not do their jobs without it. I asked what they wanted for documentation. They could not seem to give me a straight answer. They just kept using circular phrases like “Documentation. You know. Documentation”. This seemed like a new kind-of (pseudo) problem, because I don’t know of any systems that come with user docs any more. So, I wasn’t sure what I would make for docs anyway. For a moment, I even checked if it was April fools’ day or something. No, it was mid-November. So what did they actually want?

I figured I could look at the old documentation and see what it contained. If I could produce similar documentation, that should be enough. I was surprised to find that the old documentation consisted of recovery steps. You see, the old system went down frequently. In fact, it went down so frequently that somebody wrote-down the steps to restart or recover the system when it went down. Apparently, you could not just reboot the old system and expect it to work. No. It consisted of several sub-systems that were heavily dependent on other sub-systems. You had to restart several processes, in the right order, or it would not work.

Making similar documentation was going to be a problem, because things didn’t work like that anymore. My team knew how much of a headache the system stability and restart procedures had been. So we spent time stabilizing the system so it would not go down, or if it did, it would recover itself, without human intervention. It was all automated now. We also determined that some of the systems were not worth fixing. It would take less time to replace them with newer, more stable systems. So now, there were no restart procedures. You didn’t need to restart anything. If you did, the order didn’t matter anymore. Our fixes had obsoleted the old instructions and their primary purpose. Once we explained that to the support staff, they should be able to relax and get over the whole “missing documentation” thing.

Still, the support staff wanted “documentation”. I couldn’t make sense of it, other than: we had lost their security-blanket or something. It was even a little funny, because I began to imagine them spending all of their new free-time pacing the floor, worrying about those docs. The reality was much more irritating. They were spending their free time campaigning (to various managers) for the dev team to give them these missing docs. I never expected such a reaction. It didn’t seem like they were going to give up until they got new docs.

Naturally, my boss was getting an ear-full of this new rabble. I explained the real situation to her. She seemed to understand, but still wanted the problem resolved. “Produce something useful to satisfy them”. Nothing specific. Just give them some documentation so they stop complaining. Put some grease on that squeaky wheel.

Since they could not articulate what they wanted, I took a shot at giving them something that I felt would be useful to them. It was everything that a programmer or sys-admin would need to know about the new system(s). If something broke (which was unlikely), here was a list of server names, apps and web addresses, matched-up with a list of people (on my team) to contact.

No luck. It was ten pages of paper-weight ottoman. It just sat on a desk. Nobody used it. I got criticized. (and a little frustrated)

I figured if they liked the old document, I could simply update it and they would have their security blanket back with an “april-fresh scent”. I took their original document and did a find-replace with all of the old names and all of the new names. I also had to remove the pages that didn’t apply any more. Unfortunately, it cut the document down from 14 pages to 4 and those four pages seemed like the same paragraph had been copy/pasted ten times. They noticed that immediately. It didn’t satisfy them.

So, I started searching the web for a clear definition of “documentation” and examples or templates for the type of documentation that I should supply them.

In part 2, I will discuss my findings…


About Tim Golisch

I'm a geek. I do geeky things.
This entry was posted in Documentation, IT Psychology, Lessons Learned. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s