SQLChicken.com

SQL Server DBA Tips & Tricks

By

System Documentation: What’s Your Method?

As a system administrator it’s your job to know the ins and outs of the systems you manage. But are you the only cog keeping that particular wheel turning? If you were to leave your current position, or God forbid, something were to happen to you would your company be able to move forward without you without ill effect? This is where proper documentation becomes a crucial part of your job.

Now some would argue that if you document your responsibilities/job/systems/etc you become dispensable. While yes that could be true I dare to say that you really shouldn’t have to worry about that. In my opinion if you’re doing your job, and doing a good job at it, those who matter will notice and this becomes a non-issue. Properly documenting your system if anything then becomes an aid to you to help you do your job better. Yesterday Jonathan Kehayias (Blog | Twitter) wrote a great article on the importance of good documentation. If you get a chance I highly suggest you give that a read since it brings up some great points that include turnover, management, and compliance auditing.

Currently I’m trying to get a handle on the documentation of my systems at work. At the moment my current thought is to create a Word document template that simply has fill-in-the-blank type fields and for every new system that comes online I simply fill out a new form. These forms will be kept in our Sharepoint site and that way those who need access to them (i.e. on-call personnel, Help Desk staff, other system admins, etc.) know where to find them. Of course one could argue the problem with this method is that people who don’t necessarily NEED to see everything in that documentation have access to it. To that I say this, why not? I may take a little flack for saying this but here goes nothing. I believe the world of IT has drastically changed in the last few years (duh). Granted I’m still young but from what I’ve witnessed we are coming from shops where mainframes were king and jobs and knowledge were extremely siloed. Now before you start blasting me on silos, I know they still exist but go with me on this.

In today’s IT world there are simply so many things flying at us at all times. With the rate of new technologies coming out and with organizations trying to do more with less in this economy I think its more important than ever to make knowledge transparent across the enterprise. If someone wants to know what I do as a DBA why not let them know? That person could be interested in jumping in the administration world themselves and just need the basic knowledge and understanding to do so. Another example would be explaining to a project manager the technical pieces of the project they’re managing. How many times have you seen a project dumped in your lap and the necessary components are things that you either A) Don’t support B) Have no in-house knowledge of the necessary technologies.

From my experience knowledge dissemination becomes all the more vital as systems become more tightly integrated. Look at the Microsoft suite of products. Sharepoint is a collaborative portal designed to let people across teams and enterprises share and disseminate (damn I love this word) knowledge with ease. Well in order to stand this product up you’ll need someone who understands databases and their management/administration, someone who understands architectures and how best to implement them, maybe a trainer to let end users understand how this new technology works, desktop personnel to understand the technology and how to troubleshoot it, etc, etc.

As I’m writing I’m realizing I’m really digressing from my original point which is about documentation methodologies. I’ve laid out my general plan for documentation of systems but my original intention of this post (besides my slight soapbox rant up there) was to see how the rest of you guys/gals handle your documentation. Strict methodology and templates? Random documents thrown out on a shared drive or somewhere on your drive? None? Let me hear from you in the comments.

Share
  • Eugenie

    Jorge,
    Great job on the presentation at SpaceCoast SQL User’s Group.

    My comment on system and network documentation boils down to the simple and obvious: Just Do It.

    In a related vein, you might enjoy reading Dr. Halamka’s post on changes made as a result of the BIDMC network outage:

    http://geekdoctor.blogspot.com/2008/03/caregroup-network-outage.html

    You might find his comments add weight to your excellent points.

    Best regards,
    Eugenie