I’ve been thinking recently about who writes the best documentation. Not including a professional technical writer (although they actually do fit into my conclusion). On first thought I would have thought the SME (subject matter expert) would of course write the best documentation, because they understand the processes best. Upon further thought (and some experiences) I’ve changed my mind. I have found the best documentation is written by someone who is NOT the SME. Now I don’t mean someone who doesn’t know anything about the process. But say someone who has some knowledge and skill, just enough to actually do the work. In fact in some ways I think the closer to that bottom edge the better. Why you might ask? Details. The person who has the hardest time with the work is going to provide the most details in the documentation.

For example our team finished doing a disaster recovery test for a new server several years ago. I ended up writing the documentation. I did my best. I used lots of images, lots of description. It wasn’t until one of my co-workers used my documentation to do the same recovery that I realized how much I had missed. One of the last steps in the document was “Restore the user databases.” Well to me that was more than enough detail. Turns out I was wrong. My co-worker and I went back and re-worked the document and by the time we were done it was twice as long. Instead of “Restore the user databases.” There were steps on getting the list of databases, how to get the required backup files, examples of recover scripts and a walk through of doing the recover using the UI among other useful details.

So why is that kind of detail important? Well if we were to ever have a true disaster I might not be available, or for that matter might be available but working on recovering something else. I’m not available, and the instance needs to be restored, so the documentation get’s broken out. Now who is going to do the recovery? You might get lucky, the person who ends up using the documentation may not need all of the details you provide, but what if they do?

DR documentation is just one example. How about the documentation for some other kind of process? Say re-indexing, or a batch load that runs each night. Well if the process goes down and I’m not the one on call I certainly don’t want to get woken up at 3am just because I failed to add some detail to the documentation.

Recently our department has decided to do huge amounts of cross training and all that documentation has come in really handy. Particularly when I’ve been on call, it’s 3 in the morning and I’m looking at something I’ve never worked on before. It’s nice to have enough documentation to be able to resolve the problem without having to wake anyone else up. And believe me, when the problem is a tablespace in DB2 for zOS that is stuck in copy pending I need all of the details I can get.

Filed under: Documentation Tagged: Documentation