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

Your Lack of Documentation is Costing You More Than You Think

You’ve got a mountain of work to get done and not enough time to do it in. There’s simply just not enough time for you to worry about documentation right now but that’s ok though because you plan to come back to it later. Let me guess, you’re still working on that part.

The task itself was completed and the job got done, so on to the next item then. It’s no big deal right? Substitute here any of the numerous other excuses, woops sorry I mean reasons, that I’m sure you’ve probably heard yourself, my personal favourite of course “Documentation is boring anyway”. Yeah sure it can be but that’s just not the sort of talk you want to hear from any player on your team now is it.

The Costs Are Real

"Do you know the costs?"

Why is documentation so often considered only as an afterthought, a nice to have? Perhaps it’s because the effects of neglecting it are not immediately clear for us to see.  Be under no illusion however, there are some very real costs to not having documentation.

  • Slower response to issues
    • It takes longer to troubleshoot issues when you’re flying blind or trying to wing it.
    • What happens when you are out of the office and the weekend support team need to provide cover for the application platform?
    • What process do you need to follow to deploy your application platform to another site? (Please tell me you have a documented DR plan!)
  • Increased development time
    • How does that awesome and albeit complex stored procedure you wrote work again?
    • If it takes you hours to pick it up again how long is going to take someone else in your team?
    • Less time for you to be working other tasks.
  • Lost Revenue
    • Wasting time costs money.
    • The longer it takes you to resolve an issue the more cost to your customers and your business.
  • Knowledge Loss
    • What happens when you move on from the company?

Get Your House in Order

"Is Your Documentation in Order?"

Knowledge is power after all right, yes it’s a cliché but it’s without a doubt true and the faster you can either consume knowledge yourself or share it with your peers the more time you have to get the real work done.

Wouldn’t you much rather:

  • Be ready to react to incidents faster with defined processes and procedures.
  • Get your new team members in the game quicker by bringing them up to speed on things.
  • Share your success stories with other groups/teams within the company. Perhaps they can use your documented solutions as a framework or ideas for their own solutions.
  • Pick up your own work once again that much faster when you revisit it.

As a Database Administrator it’s important that you Think Defensively. Stop putting documentation off and start giving it the attention and priority that you know it really deserves.

I’m not the only one that thinks you ought to be getting your documentation done. Jonathan Keyhayias(Blog|Twitter) has talked about The Importance of Good Documentation and Brad McGehee(Blog|Twitter) has dedicated a huge amount of time and effort to produce detailed SQL Server check lists for you to use, covering areas such as Security,Monitoring, Hardware and Maintenance.

The Best Database Administrators Document Everything

The services of Outstanding DBA’s will always be in demand, fact. You need to be doing whatever you can to maximize the time you have available to work on tasks that add value to your business.

I’ve talked about making the most of your time before when I told you that The Best Database Administrators Automate Everything, well guess what, they also document everything well ok most stuff then :-) but when you consider the costs, can you really afford not to get it done?

What do you think about documentation?

John Sansom - SQL Server DBA in the UK

John Sansom (Blog | Twitter) is a Microsoft Certified Master (MCM) of SQL Server and publisher of the free SQL community ebook DBA JumpStart, an inspiring collection of advice for Data Professionals, written by 20 SQL Server experts. Awarded the Microsoft Community Contributor(MCC) award, John is a prolific blogger and can be found regularly writing about SQL Server and Professional Development over at www.johnsansom.com.


Posted by Anonymous on 1 February 2011

Pingback from  Twitter Trackbacks for                 SQL Server Central, Your Lack of Documentation is Costing You More Than You Think - John Sansom - SQL Server DBA in the UK         [sqlservercentral.com]        on Topsy.com

Posted by Stephanie J Brown on 6 February 2011

Well said!  And applicable to all areas beyond the DBA, as well.  Those of us that document regularly know the value of it, usually six months and three projects later when something breaks, or an upgrade is needed.  It's a five-minute phone call to say "look here in the documentation" versus a half-hour phone call trying to explain where to look and what to do.

Posted by John Sansom on 6 February 2011

Thanks Stephanie!

It's so true. Just that little bit of extra effort can go a very long way.

Posted by jonathan.headland on 7 February 2011

The best documentation explains what the engineer/developer was trying to achieve, rather than explaining how the code works in detail.  Anyone can read the code and understand the detail, but what's not visible there is the intended purpose and environmental assumptions.

Without understanding the conditions under which a piece of software is intended to work, it's impossible to rely on its fitness for purpose, and the most cost-effective action then is to scrap it.

Documentation which rather "describes" what the software does, is, of course, a complete waste of money.  No sensible engineer would rely on that documentation, for it might be out of date, or wrong, and in any case, it will be no easier, conceptually, to understand than the code itself.

In short:  documentation must offer a higher level of meaning to be valuable -- and then it is very valuable.

Posted by John Sansom on 7 February 2011

Excellent points Jonathan!

Perhaps herein is the fuel for another post, what is good documentation?

Thanks for your comments.

Posted by JJ B on 7 February 2011

Wish I could give your post 6 stars.  Documentation is about being a professional, but it isn't treated that way by too many people.  Go you.

Leave a Comment

Please register or log in to leave a comment.