A DBA usually will get involved in four types of documents as listed below

• System document: This type of document is mainly to record the evidences of the working systems, such as system configuration, database parameters, hardware, OS and the related matrix between databases and applications etc. In short, this type of document helps a DBA to know what the system environment looks like.
• Process document: This type of document mainly deals with the steps of key business-valued process that a DBA cannot afford to miss one step. The typical document is a disaster recovery document, in which there will be defined procedures / DBA duties regarding how to respond to a disaster.
• User requirement document: This type of document is to record what business requirements, which facilitate a DBA to generate the corresponding data model, data constraints, or business processes model on the database system.

• Others: this includes various reports and communication-oriented documents, such as project status report, memos, meeting agenda / minutes etc, these documents may not necessarily have peer DBAs as target audience, but more likely target toward management and other business personnel

Basic Document Quality Requirements

Except for user requirement and communication-oriented documents, which can be varied hugely different depending on the real scenarios and target audience, the other two types of documents have something in common:

• Repeatable: In another word, the document cannot be ambiguous. With the document, another DBA can repeat the scenario and achieve the same result. For example, a system configuration document can be repeated again and again by another DBA, and all the result is the same, i.e. you get a system with same configuration parameters.
• Verifiable: using the document, another DBA can verify that the final results satisfy the purpose of the document. For example, using a system recovery document, another DBA can ensure that the system is totally recovered, such as the front-end applications can connect to the back-end DBs, and work properly.

Document Value Formula

It is hard to precisely quantify the value of a document. But still we can make the following assumptions:

Document Value = (Document usage life) * (Audience Number) * (Audience Position Rank) / (Document Generating Time)

Where:

• Document usage life: means how long the document is useful assuming no change to the document needed once the document is created
• Audience Number: means the larger the audience, the more impact (thus more value)  the document may have
• Audience Position Rank: means the higher the position the audience holds, the more value the document may have. This is based on the assumption that a high-ranking person is usually responsible for making bigger decision in terms of impact scope.
• Document Generating Time: The quicker a document can be generated, the more value can realized in the document

Of the four factors in the formula, as document authors, we usually cannot control the first three factors, but we definitely have the ability to impact the fourth one, i.e. Document Generating Time.

Document Evolution Path

Based on the value formula described above, we can explore some innovative ways to generate a DBA document.

My understanding is that most DBA's documents, which are technical ones (50% to 70% of a DBA's total documents), can be made similar like a financial report in the way that a financial report can be produced dynamically anytime as long as the data is available. A DBA's document can be produced in a concise, informative and fast way similarly too.

For example, if I want to generate a system configuration document, all I need to is to start a scanning application that will get the live data from the system and insert the data into a table with timestamp, and then I get these data from the table and fill the data into a pre-formatted Excel document. The document's title, purpose section, analysis rules can be stored in a table too to facilitate the document generation.

Another example, say I need to give my manager a weekly report regarding a project status, all I need to is to retrieve my project log table as follows:

            Select Project_Item_Desc, Finished_Date            

            From ProjectLog            

            Where Status = ‘MileStone'

and here ProjectLog table is automatically updated daily using a predefined protocol. For example, if my scanning job finds a document called "User Requirments.doc" in a C:\Star_War_Project folder, I will 

Update ProjectLog set Finished_Date = getdate() where item = 'user requriemnt doc done'

I believe documentation was, is and will still be the inseparable work load a DBA need to take for high-quality work. The issue here is how to maximize the document value to be aligned with business values and how to maximize the value of a DBA's time. I have seen documents piled to the ceiling, while many documents were less than  2 years old, and nobody cared to read as the system was already upgraded or replaced. I was feeling so sorry for the authors whose dedidcations and time were lost and wasted in nowhere.

I hope my proposed documentation formula can somehow serve as a rough guideline if you need to evaluate the ROI of any document you want to compose.