By: Jeremy Kadlec | Comments | Related: More > DBA Best Practices
Problem
I work for a company that has auditing requirements and with those auditing requirements comes the need to document the environment, specific processes and policies in our organization. I read your Defining and Establishing SQL Server Policies and Procedures tip and found that it was a help with the policies that we needed to have for the audit. Although document is not a very exciting topic, it is something that I need to do for my job and for my organization to meet compliance. If we do not meet compliance, our organization can have some problems, problems that I would like to avoid. Can you provide me with some suggestions on how to document our SQL Server environment? I am having a hard time just getting the information down on paper, so I need some help from the start. Thanks in advance!
Solution
If you are not a writer or someone who works at developing this skill on a regular basis, writing can be a challenge. Writing is a skill of sorts. As is the case with any skill, it is the hardest to do the first time and takes practice to improve as is the case with any sport or discipline. Let's jump into some common questions to address the need from a generic perspective.
How do I get the information down on paper?
- Scope - Make sure you clearly understand why you are writing the document and who is going to use the document.
- As an example, documentation that you write for yourself vs. an auditor vs. your DBA team are probably going to be very different. Keep this in mind and build the documentation accordingly.
- Questions - Determine the questions that need to be answered in the document.
- This takes the 'why you are writing the document' to the next level. If you need to document your environment, what are the components of the environment that are important i.e. SQL Server names, versions, databases, points of contact, business hours, etc.? Also try to think about the questions that the reader would ask? So think like that person and make sure you are answering there questions. If you are not sure, then ask them the questions so you start off on the right track.
- Format - Think about the general format of the document.
- Will the documentation have images? Will the documentation be a page or two or twenty? Do you need to write paragraphs and paragraphs of text or will bullet items do the job? Can you use URLs to additional information to keep the documentation length as short as possible?
- Outline - Outline each of the major sections that need to be written.
- Building a quick outline can go along way if you are not exactly sure how the documentation is going to end up. If you are having an issue building an outline, just get the major topics down on paper and then start to organize them in the correct order.
- Bullet Points - Once you have your outline completed, then start to build bullet points in each of the sections.
- Depending on the documentation, bullet points may be more of a benefit than pages of paragraphs. This is because the bullet items are short and sweet. You can use headings to make the bullets descriptive so someone can easily scan the page and find the information they are looking for at a glance.
- Multiple Passes - Not many people can write a document from start to finish. As such get your ideas down on paper and then move on to the next section.
- One technique that may be beneficial is to use a placeholder to denote that the section is incomplete. You could use your initials or a set of symbols. Then as you review and edit the document, you can search the document for that unique string to make sure you are not overlooking a section.
- Review - Review the document for accuracy and grammatical errors. In addition, make sure the document answers the questions intended and is written at the appropriate level for the reader.
- Once you have the document at a good place, take a step back and try to look at the document from the readers eyes. Can they follow the directions? Are the screen shots accurate? Are there sections that are not needed that should be removed or moved to an appendix?
- Delivery and Feedback - Depending on scope of the document formal or informal feedback should be requested.
- Sometimes what people want and what they get are two different things. As such, depending on the documentation it may make sense to have some early reviews with the audience to make sure it is what they are looking for from you. If it is a small set of documentation, then a final review and edits should be sufficient.
What is the right level of detail?
Coming from a very verbose person, I would say everything. In reality it makes sense to consider the topic, the audience and the purpose of the documentation. I have found that documents over a few pages typically are not read unless there is a major issue to do so. As such, organize and summarize the major points at the beginning of the document on a single page and then provide references to the remainder of the document for additional information. As a best case scenario, keep it short and sweet, but if you must, have a long document make sure it is well organized and beneficial to the reader.
Next Steps
- The next time you are faced with writing some new documentation, consider the information in this tip as a starting point.
- If you are in a situation where you start to see patterns in your documentation, consider building a template and then re-use it as necessary. This should help with the 'blank slate syndrome' and keep the documentation consistent.
- Check out these related tips:
- Defining and Establishing SQL Server Policies and Procedures
- Check out these documentation tools on the MSSQLTips.com Product Listing:
About the author
Jeremy Kadlec is a Co-Founder, Editor and Author at MSSQLTips.com with more than 300 contributions. He is also the CTO @ Edgewood Solutions and a six-time SQL Server MVP. Jeremy brings 20+ years of SQL Server DBA and Developer experience to the community after earning a bachelor's degree from SSU and master's from UMBC.This author pledges the content of this article is based on professional experience and not AI generated.
View all my tips
