An Unlikely Taste for Documentation and Archiving

  • Comments posted to this topic are about the item An Unlikely Taste for Documentation and Archiving

    Best wishes,
    Phil Factor

  • 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

  • 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!!!

  • @gary

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

    Best wishes,
    Phil Factor

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

  • 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?

  • @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

  • 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!!!

  • 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

  • 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]

  • 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.


    [font="Tahoma"]Personal blog relating fishing to database administration:[/font]

    [font="Comic Sans MS"]https://davegugg.wordpress.com[/url]/[/font]

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

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