Documentation

Documentation

(…Or how I learned to stop procrastinating and love tolerate a chore necessary task)

Do you document? Do you document well?

As I told Paul Randal (twitter, blog) today on twitter, this blog post was inspired by an observation in the shower and a recent question by Brent Ozar (twitter, blog). You didn’t need to know that but now you do. I happened to read the back of the body wash and noticed the directions had some minor flaws. It made me think of some of the documentation I have produced or tried to rely on and some common mistakes. Let’s dissect the directions on the soap:

“Directions for Daily use in shower or bath: Squeeze desired amount of product onto wet cloth or cleansing pouf. Work into a lather. Rinse Off”

The Good #1 – The directions exist

A colleague often answers my comments on performance with, “The perfect is the enemy of the good” now we won’t get into perceptions of what “perfect” means and what “good” means 🙂 but in some regard he is right. If you have documentation and it is useful and not dangerously misinforming people it is a start (a draft) and it’s okay to write and publish a draft. If your documentation will allow you to go on vacation, not have dreams about work and let your backup handle the majority of the tasks well then it’s a great start. Get your favorite document editing tool and at least start something. Not starting documentation because you are afraid of missing something, can’t figure out where to start, etc. is a disservice to you and your organization.

The Bad # 1 – There are assumptions

Assumptions are in two flavors here. An assumption that one already follows a process (“For daily use..” If I didn’t shower daily, I’d have a lot more time for blog posts at night because the couch is uncomfortable for sleeping but what if I didn’t?).

Alright so let’s be serious with the other assumption. They assume the person reading the instructions knows what a “pouf” is (i’ll admit it.. I know what one is… Alright, fine I will admit it – I have and use one…) They assume your idea of the “desired” amount is sufficient.

• The assumptions, definitions, overview and/or introduction sections of a document should be used. Let the audience know what you expect of them, define terms that can be ambiguous at your organization and tell them the goal you had in writing the document.
• You should write to your audience (and think about the future audience). Can someone pick up the document (especially if it is a runbook, deployment guide, etc.) and do what is required without a Vulcan mind meld with you? If not you are assuming too much.
• Test (I know. I harp on testing a lot) your document. Give it to someone who may not be the other DBA on your team but could potentially be in a position to have to rely on the document. Can they follow it? Do you have an environment you can deploy to after dev/integration where a deploy guide is written/unit tested? Someplace where someone other than the author can prove out the steps?

The bad #2 – There are missing steps

This can be lumped with assumptions but I felt it needed a special callout. The piece that caught my eye this morning was “Work into a lather. Rinse off.” If I were to follow the directions literally, I could see myself squeezing the product onto my pouf (Wipe that smirk off your face), and just lathering it up and then rinsing the pouf off. Over time I would have less drive by attacks at my cube but only because of the smell –> I would simply not be clean.

They are assuming (see I told you it could be lumped with assumptions) that the reader knows how to bathe (then why even bother with the directions?). Don’t write a document with obvious information missing because it is obvious to you. 

Ask yourself, “what is the goal of the document?” Hopefully its in the objective/introduction/overview section. Read your document and ask if it meets the goal. Have someone that isn’t always finishing your sentences read it and see if they agree.

Why do I embrace documentation now?

• I am making myself more replaceable – I like uninterrupted vacations, I like letting other people do deployments. Earlier in my career I wanted to always be that go to guy (I still enjoy helping and love gaining and sharing knowledge). I used to love to be that one who saved the day at 2:00AM and led the conference call to do so. Now I like helping others do that. Will I get the “great job!” e-mail from a CIO for it? Probably not but I’ll get to spend time with the family. I can’t think of what kind of fancy thank you e-mail, “we did it” dinner or little plastic trophy beats William or Rachael’s laughter.
• I can say “If you read my maintenance recommendations…” – No, that’s not a great attitude. What I mean is I can let my document be a force multiplier when I can’t get more living, breathing DBAs. I can create templates, suggestions, checklists with steps to create and let “reluctant DBAs” in the infrastructure or deployment teams do some of the menial tasks. They can still call me if there is an issue but if I don’t assume and state the obvious it’s less likely.
• A proposal on paper beats a hallway conversation – Talking is great (I have been know to be a chatty person. I know, you are shocked) but handing a simple document with pros/cons and a suggestion can go a long way. Provide justification for the server maintenance products, provide justification for that indentured servant Jr. DBA, Provide a rationale for going to the PASS Summit, etc.)
• Maybe, just maybe, when that problem arises again, we can solve it quicker – Even just using a blog as a knowledge base, a well organized e-mail folder structure, etc. can help deal with that problem that “happened at year end the past 3 years… what was it again? You had to do something to the readerform switch in the whoozywhatzy table… Next year we’ll be ready for it!!”