The Lone DBA – Why Documentation Is Good
Posted by Josh | Posted in The Lone DBA | Posted on 10-19-2011
0
This post is the fifth in an ongoing series about how to survive as the only DBA in your organization. Since October of last year, I’ve been assigned to a team that is responsible for owning and maintaining the development infrastructure. It’s a great team of seasoned professionals, but not a single other DBA. As a result, I’ve had to think very carefully about how I go about my daily work, so as to give our customers consistently good service, while still allowing those without a lot of SQL Server related knowledge to pick up my work when I’m not available.
Why I Hate Writing Documentation
The answers to this question are pretty straightforward, but as we’ll see, there’s counter-arguments in most cases.
It Makes The Work Take Longer
It’s true that documenting a process means taking longer to actually complete the work. Consider the added time to take screenshots, write down steps, and (of course) test to ensure completeness, and it could well double the amount of time required.
On the other hand, this increase in time should be pretty much a one-time occurence, with occasional tune-ups of the documentation required as procedures change and evolve. So really, it’s not that much extra work.
The Logic Is Too Complex To Document
STOP!
On this one I have to call my own bullshit. There is no such thing as a process that is too complex to document. It may take pages upon pages of screenshots and steps, and turn into a forty page monstrosity, but it’s still quantifiable.
So let’s be honest here: what we’re really saying is that we’re too lazy to take the time to document our process, because it would take a long time. Everyone agreed? Let’s just suck it up then and move on, because laziness is never an excuse for bad practice.
It’s Really Boring
Well that one is easy to answer. You see, all you have to do is… um… well…
*thinks*
Okay, you’ve got me. I can’t really think of a way to make writing documentation fun. Oh well, there are some things in our jobs that just aren’t going to be fun. All we can do is minimize them, perhaps by automating things as much as possible?
Why I Love Writing Documentation
It Lets Me Outsource
If I have a process thoroughly documented, it makes it easier to hand off to a junior DBA or other staff. This then frees me up to do more interesting or important things. Why spend time doing things that someone else could do just as well, when I could be doing things that provide real value to my customers?
It Ensures Consistent Service
To me this is the big one. If my documentation is complete, I can leave for vacation knowing that my customers will be well taken care of while I’m gone. Good customer service means consistency: they provide the same input (a request to restore a database), and receive the same output (the database is restored and permissions re-granted). Without documentation there’s no guarantee that someone else on my team would handle the request the same way I would; with it, the customer won’t even notice a difference.
So now I’ll pose a question to the community: How do you motivate yourself to write documentation? How do you ensure it is kept up to date?
