Who writes your documentation?
4April 22, 2013 by Kenneth Fisher
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.
SQL Studies 
Nice write-up and thought. I hate documentation and was never really any good at it. I’m not good at process documentation either, such as when you might document steps for a data load into a new system, for instance. I get too wordy, verbose, and usually write in too many layers. Get sign-off on your documents for indexing, restores, etc. from the folks that will actually read and (potentially) execute the document; you’re writing it for them and not yourself.
Don’t get me wrong. Documentation is certainly not something I enjoy, or I would have gone on to be a technical writer :). We are currently having to “catch up” on a lot of documentation as we do all of our cross training. It’s helpful stuff and good practice. We have merged together 6 different divisions in the last couple of years so there are a lot of different tasks that need to be documented.
Unles you have a steel like memory and are guaranteed to never forget anything no matter how small the detail then when you document you are at least sometimes documenting for yourself as well as for others. I can;t count how many times my making detailed notes in some script has saved me when at some late point I had to revisit something that was changed.
I agree completely. Actually you would be amazed how often I use my own blog as “documentation”. The nice thing about having someone who is a “Junior” doing the documentation (or at least reviewing it) is they find a lot more of those details that more “Senior” people tend to forget.