As a DBA, documentation work is unavoidable, we need to do documentation about things we have done, for example, what code we have implemented, what configuration value we have changed, what user rights we have changed, what xxxx. In a heavily-audited environment, documentation practice is what an auditor enthusiasitcally pursues

I once worked in a company where our default documentation standard is: "Document for Dummies", i.e. the document should be detailed enough to the extent that a computer-illiterate person (assuming the person knows how to click mouse and type keyboard) should be able to read the document and repeat what I, a senior DBA, has done as described in the document. This standard killed me. Just an example here, say I wanted to document how I set up log-shipping in SQL Server 2000. As a matter of fact, MS has a whitepaper about how to set up log-shipping (http://support.microsoft.com/support/sql/content/2000papers/LogShippingFinal.asp), but no, it did not meet the standard of my management as I was challenged by the question "Do you think Ms. xxx can do the log-shipping by following the instructions on this document?" (note. Ms. xxx is our data entry clerk with no knowledge of database at all). I thouht to myself, "Well, no, Ms. xxx definitely cannot do this with this document as she even does not know where to start SQL Server Enterprise Manager, let alone how to create a shared folder used in the logshipping".

So long story short, I completely reinvented the wheel based on the MS whitepaper, however, I had to add more details, such as pre-implementation guide, details including how to create a sharefolder, each step is companioned with a screen-shot, and how to start a SQL Server Enterprise Manger  by saying, "Go to Start, click Program, and click SQL Server 2000 Program folder, and then click SQL Server Enterprise Manager and so and so".... After doing this for some time, I realized that I have more important things to do and my time can be better utilized than doing these so-called "docouments for dummies".

In the following months, I was approached by a friend who works for a staffing company, and I was recommended to a company who was looking for a senior DBA. I went to see the company's hiring manager, and at the end when asked why I left the current employer, I told the truth that I disliked the documentation practice there. Two days later, my friend in the staffing company gave me feedback, saying "Jeffrey, you are the front-runner technically speaking, but they are worried that you are incapable of doing documentation, can you give me something that I can address their concerns?". My friend's request prompted me to give a deep thought regarding documentation, and I try to answer the following questions:

What documentation DBA needs to prepare and who are the targeted readers?

What is the ROI of any documentation? Is there a foruma that we can use as a framework for this ROI calculation?

How can we produce the documentation efficiently? Is there any automatic way to facilitate documentation?

I'll try to address these questions in my next post.