SQL Clone
SQLServerCentral is supported by Redgate
Log in  ::  Register  ::  Not logged in

On the Importance of Documentation...

It seems that I keep inheriting old systems that provide a singular, albeit mission critical, function to their owners. In the majority of these cases, I have encountered numerous small applications that were designed to run in a standalone environment to solve a very narrow problem or set of problems. The person who supports the application - which is very often the same person that wrote the code behind it - eventually departs the company without documenting his/her work. Somehow these database apps keep chugging along for months or years until one day a tragedy occurs - like a folder being renamed or a mapped drive being deleted. My phone rings, and I step out of my database analyst role and into my Sherlock Holmes coat.

I'm sure you've all been there. A problem that should take you 30 minutes to fix actually costs you two days because you have to reverse engineer the environment to figure out what the programmer or database designer was thinking. These kind of things get me more irritated than a cowboy without a saddle on a hot summer day.

It's not just for the sake of others that you document. I can't tell you how many times I've looked over some of my own handiwork and wondered what I had been thinking when I designed a feature or configured a particular database object. With few exceptions, I almost always fall back on my documentation at some point, even for the most trivial of things.

So I put out the call to all of my fellow IT folks, database analysts/programmers/sysadmins/[insert your job role here]. Document, document, document. Even if you're sure no one will ever need it, document. If you are creating an ETL database that you plan to delete in 90 days, document. If you write a function that's more than three lines long, document. Your successors will thank you for it. You might even save your own job some day!

Tim Mitchell

Tim Mitchell is a business intelligence consultant, author, trainer, and Microsoft Data Platform MVP with over thirteen years of data management experience. He is the founder and principal of Tyleris Data Solutions.

Tim has spoken at international and local events including the SQL PASS Summit, SQLBits, SQL Connections, along with dozens of tech fests, code camps, and SQL Saturday events. He is coauthor of the book SSIS Design Patterns, and is a contributing author on MVP Deep Dives 2.

You can visit his website and blog at TimMitchell.net or follow him on Twitter at @Tim_Mitchell.


Posted by Esbay on 13 January 2008

I totally agree, and would add, "Document even if you aren't comfortable writing!"  Being a life-long documenter (well-trained in college), I tend to support all things documentation-related.  But conversations with co-workers have enlightened me as to why some people don't document - and it's not always that they don't see the value.  Sometimes, it's that they are self-concious.  They aren't comfortable writing, or don't think they do it well, and are concerned that whomever reads their document will be judging them.  (I blame this on over-zealous English teacher in High School, because if I had listened to the ones I had, I'd never write a word.)

Believe me, whoever reads your documentation will be very busy thanking you (think of all the good karma you're gathering), and secondarily busy fixing the problem based on your document.  The last thing on their mind is whether your vocabulary or spelling meet some 11th grade teacher's criteria.

And the more you write, the better you become (as with all things, practice brings you closer to perfection).  Document in the code with comments, create a short blurb on the what and why of the project (or mini-project, for many of us).  Like Tim, I've had many times when I had to refer to my own documents six months later, and was thankful I had taken a few minutes to write the notes that saved my bacon.

Posted by DonW on 14 January 2008

I also agree.  It might not even be a case of saving your job, you might simply save your credibility.  When someone asks you something about that section of code and you scratch your head and have to admit you are not sure what you were doing and why, some people tend to wonder if you have any idea what you are doing, period.  It won't matter if you are able to tell them an hour later what was behind the code (if you do figure it out) you have still put a dent in your creditility that will take a long time to remove.  I speak from first-hand experience.

Leave a Comment

Please register or log in to leave a comment.