Skip to content

Personal tools
You are here: Home » Of Interest » Articles of Interest » No Reading Between the Lines: The Importance of Documenting
Seeking new owner for this high-traffic site.
Tap into the potential of this DBA community to expand your business! Interested? Contact us today.
Who Are You?
I am a:
Mainframe True Believer
Distributed Fast-tracker

[ Results | Polls ]
Votes : 3558

No Reading Between the Lines: The Importance of Documenting

By James F. Koopmann

As a DBA, do you know what you should be doing? (Do you know what you did yesterday?) It really amazes me, how many articles and books I have read that painstakingly tell what a DBA is, what they should be doing, and how they organizationally fit within a company. And I continually get e-mails from individuals asking how they can become a DBA, what training they should have, and what types of jobs they should accept or decline in their quest to DBA stardom.

Don’t get me wrong — I do believe that there are real tasks, duties, and responsibilities that every DBA should learn to do on a daily basis. But I have a bone to pick with those who have the necessary skill sets, but who are wasting time trying to figure out such “macro” principles before they understand their own system environments. For instance, it makes no sense for a DBA to be spending time trying to understand which SQL statements are consuming the most physical reads when there isn’t an internal process or mechanism to reduce the reads by altering an application or adding an index. Yes, I have seen shops in which the DBA staff is so hamstrung by the development group that adding an index without development approval is a cardinal sin and excommunication is eminent. Under these circumstances, a DBA must first foster a relationship with all interested parties in order for change to occur.

To answer the age-old question, what should a DBA be doing, I have found that if you perform two very simple “bookkeeping” procedures, your job description and/or task list will become quite focused. These two simple steps are simply

      • Logging what you do and
      • Extracting and documenting the issues

If you perform these two functions well, the people or departments who are your stakeholders may actually be inspired to promote some real and positive changes.

Logging What You Do

The very first step is to begin keeping a diary or log of everything you do from this point forward, with no exceptions. My favorite method of keeping a log is to simply open up a MS Word document, key or insert the date and time, and begin tracking my every movement. My entries are typically just a cut-and-paste from the window in which I am doing my work. If I find that I can’t cut and paste from a particular  and it is necessary to completely save it, I will use a screen capture utility — you really can get as fancy or archaic as you like. The important thing to remember is to capture enough information to fully explain the issue you are working on, your timeline for completing the task, and how you ultimately accomplished it. This might seem too simple and you will no doubt be bored stiff keeping a log, but the following benefits far outweigh any pain you may have:

      1. This should be obvious, but careful documentation allows you to have a record of what you did and when you did it. This is invaluable if you need to perform the same task over again; you can easily pick up where you left off if your task spans days. Also, if for any reason you need to back-out what you have done, by simply inverting the actions you took as recorded in your log, you can follow a “recipe” approach to do so.
      2. Weekly status meetings will become easier to attend, and when your manager asks you what you have been doing with your time and what you have accomplished during the past week, you will have an answer.
      3. Your work efficiency should increase. There is nothing better than physically documenting your own work flow to alert yourself to the need to work smarter and more efficiently.

As you produce your work logs, you will soon begin to find patterns in the type of work you do and gain insights into what should be your true task list. You are now ready to extract these recurring tasks and produce a database operational manual for your use and to assist and any other DBAs on staff. Of course, some of the items you work on during the day will not really be part of a task list, but are instead problems you have encountered during normal database operations. Such issues could be associated with performance, storage, capacity, contention, and so on. The log that you have been keeping is a great place to extract and publish the remedies to these issues, so that if they ever reoccur, you will have a quick solution at hand.

Tracking Problems

Extracting and documenting those things that we do as DBAs can be somewhat daunting. But the obvious benefit of not being awakened at 3:00 a.m. because you have fully and completely documented details that someone on shift in operations needs to solve a problem should persuade you to pursue this methodology. And even if you are called at 3:00 a.m., at least you will have something in hand to help solve the problem, and allow you to go back to bed more quickly. Just remember, these operational manuals should contain everything that a DBA who is not familiar with your system environment needs to do the job — he should not be bothered with minor details of where the database boxes reside, how they are connected, what the different environments are, and how to log on to the boxes. If you don’t provide everything, chances are good that you will get that early morning phone call, and your process will be buried. Who knows, by carefully documenting your work, you might even be able to outsource remedial database operational tasks, save your company some money, and move on to other opportunities that interest you.

Documenting and Categorizing Work

Here are a few of the ways I like to categorize the work I document. The following should be enough to help you get started on your personal quest to document the importance of the items you work on, how you solve the problems, and better yet, how someone else can handle the issues you have isolated. Also, I have provided a sample .pdf file on the format of what I use to track these problems.

Core Area

Availability  The amount of time the database is available to work on requests. Uptime, downtime, or mean time to failure (MTTF).
Recoverability The ability to recover the database from failure.
Reliability The probability of errors or the mean time between errors.
Security The ability of your database to handle attacks.
Planning The tracking of your database system to enable modifications to meet future strategic business needs.

Focus Area

Environment Are the systems on which your databases run configured in the best possible way to meet or exceed best practices and standards?
Physical Layout Are the physical resources that your database consumes adequate to support the operations of your database and users?
Storage How much disk space is required by your databases? While this could be part of the physical layout focus area, it is such a large issue in itself that I categorize it as a separate focus area.
Schema Are the logical structures defined that allow for access to data?
Workload What are the requests made of the database, including queries, DDL, and administrative tasks?
Throughput What is your database's productivity? This is measured in the rate (requests per unit of time) at which requests can be performed by your database.
Response What is the time interval between a request for work and the database's response to that request? Does the system deliver results that meet end user needs?
Utilization How much time does the database use to work on a request? This is the ratio of busy time and total elapsed time over a given period. The period during which a resource is not being used is called the “idle time”; the resource with the highest utilization is called the “bottleneck.” Performance optimizations at this bottleneck offer the highest payoff, so finding the utilization of various resources inside the system is an important part of performance evaluation.



You and anyone in the database administrative staff responsible for maintaining the corporate databases.


 Management to whom you directly report.


Management levels above your direct management.


Critical That which is necessary to maintain a minimum level of performance.
Required That which is necessary to improve the system.
Optional That which is necessary to achieve Nirvana.
Note Information only.


Always indicate the database you are working on. Don’t forget to note the database version, since how you detect problems and find solutions are sometimes dependent on this information. You might also like to explain for what the database is used, how to connect to it, or any other database-specific information.


Define the nature of the problem. If you can’t make a clear statement about what the problem is, you should refocus your attention on something else.

Why Important

Every problem should have with it an explanation of why the solution to a problem is important.

Data Needed

You should be able to provide a road map of the source for the data you are using for analysis. This can be as easy as showing the SQL statements.


In this methodology, you base a recommendation for action on insights you’ve derived from the data you have extracted. (Typically this is pseudo code to explain the logic on which you support your recommendation.)


Now The problem should be solved when discovered.


Because of your analysis and recommendation, the problem does not need to be solved immediately, but should be handled within a given time frame.
Leisure There are no negative consequences for the database and the company if a problem is never solved. Such issues serve more to create an environment that functions to meet standards but will not fail if we don’t implement them.


James F. Koopmann is committed to providing guidance and technical savvy to solve today's operational issues as well as give insight to tomorrow's opportunities. Koopmann is an accomplished author with technical papers in Oracle publications such as Oracle Magazine, Oracle Professional, Exploring Oracle, various local Oracle user group publications and across the Web. He is an Oracle Certified Professional DBA and speaker at local and international Oracle user groups. He may be reached at or

Contributors : James F. Koopmann
Last modified 2005-06-30 03:16 AM
Transaction Management
Reduce downtime and increase repeat sales by improving end-user experience.
Free White Paper
Database Recovery
Feeling the increased demands on data protection and storage requirements?
Download Free Report!

Powered by Plone