An Unlikely Taste for Documentation and Archiving

Question

An Unlikely Taste for Documentation and Archiving

Phil Factor

SSC-Insane

Points: 20244
More actions
November 8, 2014 at 11:17 am

#292365

Comments posted to this topic are about the item An Unlikely Taste for Documentation and Archiving
Best wishes,
Phil Factor

Viewing 11 posts - 1 through 10 (of 10 total)

You must be logged in to reply to this topic. Login to reply

Charles Kincaid SSChampion Points: 13593 More actions · Answer 1

This is a great question. We would put out deployment scripts and it fell to a person that was not a DBA to run them. There was always a trained individual close at hand (working from home) who not only had copies of the scripts but documentation as to what the purpose of the is. This way when (not if) something went wrong it was easy to fix less than nominal outcomes. Yes, all of the scripts were version controlled. The VC software required description on check in.

For us we were already doing that sort of thing with the application software so extending that to databases was sort of natural.

ATBCharles Kincaid

Gary Varga SSC Guru Points: 82166 More actions · Answer 2

Arguably, keeping a "service history" of the database is useful i.e. capture when a script is run (including the version of the script). That way anyone can understand the context of any issues that arise.

Gaz

-- Stop your grinnin' and drop your linen...they're everywhere!!!

Phil Factor SSC-Insane Points: 20244 More actions · Answer 3

@gary

Hmm. Yes, I missed that one. Good point.

Best wishes,
Phil Factor

Robert.Sterbal SSCrazy Points: 2855 More actions · Answer 4

Along the same lines, a checkout script after something is run, and can be rerun can be beneficial.

Matt Miller (4) SSC Guru Points: 124210 More actions · Answer 5

There's also the fact that your documentation will probably survive any unfortunate encounter any one of us might have with a bus. Nevermind the prospect of untimely demises, etc..., it is encumbent on every role to leave behind enough information for the organization to pick up what we've done. A backup of existing scripts (even stored in a historical form) isn't documentation, since it only captures WHAT was done.

The value of documentation increases when it provides insight in the WHY, the consequences of the HOW, and the reasons as of the WHEN you did the WHAT. That's always been why "self-documenting code" isn't.

----------------------------------------------------------------------------------
Your lack of planning does not constitute an emergency on my part...unless you're my manager...or a director and above...or a really loud-spoken end-user..All right - what was my emergency again?

Phil Factor SSC-Insane Points: 20244 More actions · Answer 6

@Matt. Yes, true. Nobody in IT should ever be 'indispensable'. Even if one finds the thought of being mortal as ridiculous, keeping the documentation up-to-date means tranquil holidays. That's good enough for me.

Best wishes,
Phil Factor

Gary Varga SSC Guru Points: 82166 More actions · Answer 7

Matt Miller (#4) (11/10/2014)
...That's always been why "self-documenting code" isn't.

So true but I am always surprised at how many really smart people think otherwise. Especially in the dev world when they think that by naming things well and providing unit tests is adequate. One usually finds that these people come in, develop software then move to the next greenfield project.

Gaz

-- Stop your grinnin' and drop your linen...they're everywhere!!!

Charles Kincaid SSChampion Points: 13593 More actions · Answer 8

Phil Factor (11/10/2014)
Nobody in IT should ever be 'indispensable'. Even if one finds the thought of being mortal as ridiculous, keeping the documentation up-to-date means tranquil holidays.

At one company we had a policy that no more then three employees could ride in the same car.

@mat you have my point in that documentation should have the WHY and WHEN. Self documenting is all about the WHAT.

ATBCharles Kincaid

Wayne West SSC-Insane Points: 22586 More actions · Answer 9

Charles Kincaid (11/10/2014)
At one company we had a policy that no more then three employees could ride in the same car.

In 1985 one of the key people behind the original IBM PC, along with six others from their group and in many cases their spouses, were killed in a plane crash returning to Texas from a conference in Florida. It's definitely a reasonable policy for critical people.

I had a personal policy, before version control software was so prevalent, of scripting out everything in my databases as part of EOM processes. I can't say that I needed it very often, but it definitely would have been my butt if I hadn't had it.

-----
[font="Arial"]Knowledge is of two kinds. We know a subject ourselves or we know where we can find information upon it. --Samuel Johnson[/font]

david.gugg SSCertifiable Points: 6096 More actions · Answer 10

I’ve only got a finite supply of enthusiasm for communicating with myself.

I love this quote.

I recently realized my lack of documentation is detrimental as I considered moving to a new company. I realized all the awesome stuff I'd set up will be awfully hard for the next DBA to use without good documentation. Now I'm working on putting a good percentage of my time each week into documentation so that if/when I do move on, the transition is easy for my current company.

Be still, and know that I am God - Psalm 46:10