Documentation: Day 2

As a reminder, we have one more day before this weeks giveaway is over. All you need is a single comment on this thread. The winner will be announced Wednesday. We have more than a few people in the running this week! Good luck to you all.

/**************************************
Created by: Bill Barnes

Created: 12/9/2013 - 0728

Purpose: Run Document: To spread the word on good documentation

Description: There are multiple ways to document your code and your projects. While I've never heard a person say they like to document their code, it's invaluable to anyone taking over a new job or looking for code from years past. I know, I know... no one likes documentation. Nothing makes your day longer than looking at 10,000 lines of code without a single comment and you get tasked with writing it all down. You'll thank yourself later for doing it though!

Updates: Don't forget to comment for a free month of Pluralsight and the book giveaway at the end of the month.

12/9/2013 - 0729 Adding a header.

12/9/2013 - 0735 Creating a time line.

12/9/2013 - 1352 We all need smiley faces. ^.~
**************************************/

A few of my favorite places to find comments are listed below.

Stored Procedures, Jobs and Packages

At the top of stored procedures and jobs is a great place to write a little blurb showing who wrote it, when, and why it was written in the first place. Working in a place that has a lot of SSIS packages, it's simply wonderful seeing a quick comment that shows who wrote it, when it breaks, what parts can be restarted without causing duplication of data and where any fix scripts are if it does break. /in love/

Normal Code

As always, at the top showing what this process does and who authored it, you can also put an update section showing changes and hot fixes for faster dissection of the code. Throughout the code explaining what each section does or what it interacts with so I can use it to trace issues faster.

Hot Fixes and Temporary Changes

Anywhere there is a hot fix or temporary change. Tell me what the fix does, what direct problem does it solve and what caused it to be placed in. Is there a plan to fix this in an update vs just a casual hot fix for now? Invaluable information.

Disaster Recovery

Disaster Recovery is a common place to see documentation requests. Do you need to wait for the network guys before you fail over to the DR site? Who all do you need to call? What breaks that needs to be fixed manually in the next 24 hours after a fail over? (if nothing, bravo! Sadly not all businesses can support that. Complexity makes everything harder.)

Emergency Protocols

A good grab bag style document is fantastic if you need to drive or fly to your DR site and set the whole thing up from backups right then. What order does your site need to be configured in? How much data can be lost? What order do the databases need to be brought back on line first? What jobs need to be disabled/enabled at the new site? Who all do we need to contact?

Saving Money on Consultants

You could pay your consultants less! No, seriously! If you have good documentation, you can send it to them before they come on site or as they go through they can understand why you do what you do. If they have half day / day fee, you could save money by saving them time. Most of the ones I've seen have an initial fee and a half day or day fee after that. If you can shave a day or two off their week long visit, they get your problem fixed faster, you have less down time and they get on to the next gig faster. We can all win there.


I know, a lot of people hate documentation. I love it. Do you want to make it less impacting to your overall quality of life? There are a few simple steps that you can do to make it much easier on you.

1) As you find code that you understand, add a quick note to what it's about. Even if it's a small note, it'll help you see it and like everything else... make it better. Over time you'll add more as you go.

2) As you write the code, explain what that loop does. Write out why you're converting this int to a varchar. It'll help even while you're writing when you're looking for a specific part.

3) When you write packages or hot fixes, write out why you wrote it. It's great for keeping in a list of accomplishments. Management loves lists. Two birds, one comment.

4) Failover testing is a great point to write out what order you do everything in and what is expected to break. It's great for having reasons things act like they do.

5) Keeping the Junior DBA busy for the first week or so. When I started my first DBA spot, I was handed a pile of documentation. While it does honestly suck to read through boring word docs for a week... It was extremely helpful becoming familiar with it. When things would break, I would know where to look for common issues and problems. If one didn't exist, after the problem was fixed... one would be created.

/* Fun isn't it! I may be sick... I'm fine with that. I love documentation. It's helpful to everyone in your company and could help bridge the gap of a good review to a great one when your name is posted everywhere fixing all the problems */

--Note: If you find someone made a mistake, you can fix it one on one. Get the good vibes going.