Feb 1, 2011
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?
Feb 01, 2011 @ 22:44:43
Couldn’t agree. We actually delayed our last release for two weeks so we could make sure all the documentation was up-to-date. The docs part of both our internal and public-facing sites have heavy traffic, and it would be disastrous if we didn’t provide in-depth guides to every facet of every product–even if creating them is time consuming!
Dec 13, 2012 @ 13:37:43
Great article John.
documentation = learning.
I personally think about documentation as a way of cementing what I’ve just installed, configured or developed. It helps me remember. So I document everything.
“If you can’t explain it simply, you don’t understand it well enough. Albert Einstein” – I think of documentation in the same way.
We have a team wiki where all our documentation is saved and I pride myself in directing team members to docs that I’ve written. I use the level of follow up questions asked as an indicator on the quality of the material.
Quite simply, if there are too many questions, then it’s not good enough. It’s an easy way of learning and making sure you understand it as well as you think you do.
It’s quite similar to mentoring junior members of the team. Never shy away from the opportunity as it’s such a great learning resource. New members or juniors throw all sorts of questions at you and it really helps you revisit your theory, areas that you’ve either forgotten about or simply not visited in a while.
Dec 13, 2012 @ 17:24:28
Thanks Hugo, I appreciate it!
Having a Wiki is a great idea and tool, especially in larger organisations. I think your attitude concerning documentation is spot on and that it takes discipline to maintain such a quality level. Good form sir.
Your positive outlook on junior team members is also commendable and there I was thinking they just like to bother me
Seriously though, as you quite rightly imply, teaching is as valuable a learning experience for both student and mentor.
Thanks for your comments.
Dec 27, 2012 @ 00:54:39
A huge challenge is getting people to write “proper” documentation. The thing is when people are forced to write something they don’t want to, they end up writing a dozen page Word document that is full of waffle, interspersed with assumptions about previous knowledge, and still addresses zero of what someone would actually need to know.
What is this, exactly how does it work, how do you install it, where is the configuration stored and what changes did you make, what errors can it throw, what are some solutions to common problems?
I regularly see a dozen pages without a single one of those questions answered :-/ Then I complain the documentation is garbage, and people become even more angry about being forced to write it and refuse to do more.
“What don’t you understand?” they ask, ignoring the massive swathes of undefined text, and vague references to outside sources like, “It’s too complicated to explain how to compile and install this SQL CLR so look it up in BOL.” Would it have killed them to include their script? Oh right, they didn’t save the script, BECAUSE THEY DO EVERYTHING EVERY TIME BY HAND!
Crap documentation from crap developers leads to crap products.
Dec 28, 2012 @ 12:20:45
The phrase “Garbage In, Garbage Out” holds true to many walks of life sir.
You touch on an excellent point there, the fact that an author must always write with their audience in mind. Sometimes the author is the audience but not always.
There are of course many different types of documentation to consider, which in turn influences the nature of the content to be created. It can often be beneficial to define guidelines for how documentation should be created for your specific organisations’ needs otherwise it will be a free-for-all in terms of what results to expect.
Some folks would argue that at least some documentation is better than none at all however, I suspect you may not buy into that philosophy
Thanks for your comments Cody!