Practice Good Documentation

Having worked on teams of Db2 DBAs, largely in consulting roles, the value of good documentation is huge. This is once again clear to me as I start a position with a new company. The documentation here happens to be excellent and it makes getting a new person (me!) up to speed so much faster.

Where to Document

Where to create documentation is often the first question. My favorite documentation tool is Confluence. I find it flexible and easy to use, with a lot of documentation available online on how to use it effectively. It is excellent for teams sharing documentation, and sharing the creation and maintenance of that documentation. I’ve also worked with Microsoft Sharepoint, and it is also decent. You can even use google documents or a folder on a shared drive. Converting between locations is time consuming, but it is much easier than having no documentation at all.

What to Document

I have seen both ends of the documentation spectrum. I have seen clients with no documentation and all knowledge is in someone’s head. I’ve also worked with a client that required documentation of every configuration parameter for every database. I don’t like either end of the spectrum. At one end, there’s nowhere to even start, and at the other end, you spend so much time documenting things that are likely to change.

The art is in finding the happy medium. Documenting server names, ip addresses, instance names, ports, and database names is really the minimum. On top of that, it makes sense to document any procedures that are customized. I also like documentation of organizational Db2/database best practices – what is your standard filesystem layout, critical configuration settings, where do you store maintenance scripts, what do your maintenance scripts do, what are your HA and DR plans? This is a great resource for those new to the company, and also for you to compare systems to your own standards and best practices.

I don’t like documenting all database and database manager configuration parameter settings, however, if you’re using a configuration manager it might actually be possible. Things that are likely to change are generally not worth documenting.

How to Document

Once you come up with what to document and where to document it, there are several elements that every good document should have. I like a change log near the top of any document – even the ones in systems that help you with change management like Confluence. This allows you to see who updated a document and when, and a general overview of their changes. Here is an example of one for a document I’ve been working on lately:

Also towards the top of a document it is important to note the purpose of the document in a sentence to two. Here is an example of one for a document I’ve been working on lately:

Noting the audience the document is directed at is important. A document is written differently if it is directed at fellow DBAs, at system administrators, at developers, or at managers or users. Here is an example of one for a document I’ve been working on lately:

I am a huge fan of including a table of contents for any document longer than a single screen of data. Here is an example of one for a document I’ve been working on lately:

The meat of the document needs to be well organized and separated with Section headers and sub-section headers. This makes the table of contents section easy to generate in Confluence, Google Documents, or MS Word.

At the end of any document, it makes sense to include links to useful references or to other related documents. Here is an example of one for a document I’ve been working on lately:

Using metadata structures available to you also helps. Categorizing or tagging documents doesn’t seem like a big deal when you only have a handful of documents, but anything over 20 documents or 3 people working on the same things and it is likely to make finding what you need easier.