This is part-2 of my saga about the quest for the meaning of “documentation”. It began (in part 1), when I fixed/upgraded/overhauled a legacy system with bad stability problems. The systems were now stable. It was no-longer necessary to regularly perform the recovery procedures, described in the support documentation. This left the support team with a lot of new free-time. So they took up a new hobby: complaining about me, and how I obsoleted their documentation. And so, I began this quest to produce new support documentation that they would find “useful”.
As I searched my old textbooks and various online references for the true meaning of “documentation”, I found a pretty wide variety of definitions and answers. Now my job was to whittle-down this list, until I found which one was the correct answer.
Different kinds of documentation:
- User docs – explain how a user can use a system, in case it is not particularly obvious
- Infrastructure docs
- Wiring schemes
- Network topology
- System dependency graphs
- Security schemes
- Developer docs
- Object models & ER diagrams
- Planning / development schedule
- Bug report
- Feature queue
- Support docs
- Support Tracking System – user has a problem, track it, record the resolution
- Knowledge Base – what have others seen? How was it resolved? (consolidate the duplicates from STS)
- FAQ – most popular items from the KB
- Routing chart – If support desk cannot resolve the problem, who do they pass the ticket to?
Each of the items on this list are very useful to any developer and probably anyone on the (extended) IT team. Clearly, this encompasses the support team. Therefore, this must be the “documentation” that they asked for.
Oh, I could almost imagine how grateful the support team would be, to possess such a wealth of support knowledge, “They will give me a nice Thank-You card, at a minimum”.
So, we shared all of our development documentation with them. We did the same with the Infrastructure docs too. Why not give them everything we’ve got? Drinking from the fire hose has never tasted so good. You are welcome.
There was no standing ovation. Somehow, the support staff found all of it to be exceedingly tedious because it referred to systems that they didn’t understand. To understand them, they would need to have a background equivalent to the developers and infrastructure admins. They didn’t have that background and learning it seemed, …um, …impractical, and maybe even a little daunting. So this approach didn’t work. They still complained that they didn’t have what they needed.
We took a closer look at the list (above) to see if we missed something or if we should retry something in a different manner.
A new perspective, gave us the answer. After some foraging within our own IT resources, we discovered that the support team really already had what they needed, but they weren’t using it. They had their own Support Tracking System.
For the past two years, they had been pumping useful information into it. However, they had never taken the time to review the contents and develop a Knowledge Base from it.
We worked with the manager, to get her pointed in the right path, so they could support themselves. It was a new way of thinking and they weren’t certain it was going to work.
I wish I could tell you that they acknowledged this solution and were immediately satisfied. In reality, they were hoping we would give them a bunch of fish instead of some fishing poles. They were still feeling skeptical, after our previous failed attempts. So, they had to change their way of thinking, and assume ownership of their own solution. Once they gave it a fair try, things shifted in their direction and they were much more satisfied.
In the end, we came to the conclusion that each team really needs to build their own documentation, because they are really the only ones who know what they want and will find useful. Like any question, there are (potentially) an infinite number of wrong answers and only a few right ones. Until you can narrow your criteria and accurately express your needs, your chances of landing on a right answer is statistically very low.