Last week’s post got tremendous response! If you missed it, you can check it out here! Thank you to all of you who commented or responded, your feedback is valuable!
I learned two things from your feedback
- there are lots of DBAs that believe documentation is very important and they do document. Keep doing the good work!
- there are lots of DBAs that believe documentation is important, but don’t know where to start, what to document. The task of documenting can be overwhelming. Today’s post will help you!
Today’s post is for the DBA that wants to start documenting, and doesn’t know where to start.
Today’s post is for the DBA that already documents, and wants to see what other people are doing and thinking about documentation.
And of course, today’s post is for the DBA that doesn’t see the value in documentation, I hope I can change your mind!
What you’ll learn today:
Why Is Documentation Important For You And Why Should You Care?
You already know, I am a big fan of documenting. However you might not be convinced you need to do it.
Or maybe you do see the value, but you’re coming up with excuses, “I have no time now”, “I’ll do tomorrow”, “All my logs are gone, as my computer rebooted”, “I’ll do it next time”, “I don’t know how”,”I don’t know what”.
Does this sound familiar?
If it does, then this post is for you, keep on reading.
Let me tell you why I strongly believe documentation is important for YOU and why you should care:
- it makes your job easier.
Any future tasks/problems that you already encountered, don’t need to be figured out from scratch, if they are documented.
Many questions you might have, such as “Where is database ABC?”, “How do I troubleshoot this?”, might have an answer in your documentation.
It makes training of new DBAs much easier. You can just refer them to the documentation.
- it improves your writing skills.
Writing documentation, or better said writing GOOD documentation, requires some skills. As with any skills you get better and better by practicing them. Nobody wakes up one morning, and knows how to write killer documentation.
- it improves your thinking skills.
When you write, you are constantly verifying if what you are writing makes sense or not. Documentation has to be presented in a logical order of the events as they are occuring, and with precision. If not, the document is pretty much useless.
- it increases your knowledge.
“Repetition is the mother of skill”, said Tony Robbins, my favorite quote of all times. When you write documentation, you are actually writing down again the instructions and statements you just used. The act of repeating them, makes you retain the information better and longer.
- it shows respect and consideration towards your team.
You are willing to share your knowledge with your team. You are not just letting someone struggle, and smile under your mustache, when you know the answer, and you know they need your help.
- it can save your butt
When you get paged in the middle of the night, and you have clear instructions on what you need to do, documentation can save the day (or the night)!
When there is a crisis, and you can find instructions on how to proceed, you understand the importance of documenting.
Where To Start?
Usually when you go to a new client, or site, or new job, there is some kind of documentation available.
But there could be the case when there is zero documentation.
This could be overwhelming.
This could also give you the wrong idea of “if nobody documented before, I don’t need to document either!”
Please erase that idea from your head right away, and re-read the benefit above!
- If you start from zero, no documentation whatsoever, start documenting the following.
This is what I think the most important documents are, which cannot miss from your handbook.
– document and secure passwords for sys, system, and other accounts related to your job.
– create a diagram of databases and the servers they reside on. (relationship between data center -> server -> database -> application)
– create a document for each application, who is the supporting team. This way you know who to contact if you have a problem with the PeopleSoft application, or the in-house app.
- If there is already some kind of documentation available, start by reviewing them, and review very carefully the following:
– the site diagram of the databases and servers. If not accurate, make corrections to these documents.
– make an inventory of the existing documents, so you know what is available, and then identify what is missing.
What To Document?
This question is not so easy to answer, as each site is different, so in some cases you will have more documents than in other. DBA responsibilities might also be different from site to site. As a DBA you might also be in charge of certain applications, such as Peoplesoft, SAP, Great Plains and others.
All this will add complexity to the documentation.
I want to give you a mind map, of what the structure of the DBA Handbook or DBA Documentation could look like! I am sure there are many other categories to add, but this could be your starting point.
Click on the image to get the full size, and feel free to print it!
Let me know what you think about it! I read every email and comment!
If you enjoyed this article, and would like to learn more about databases, please sign up below, and you will receive
The Ultimate 3 Step Guide To Find The Root Cause Of The Slow Running SQL!