The sense and nonsense of (database) documentation

You know the drill. Documentation. The underrated and severely underrated baby of automation. "The code is self-explanatory," "Read The Fine Manual" and "We'll do that later". Common comments. Good management is obviously about solid content knowledge. But also do not underestimate the recording of agreements, actions and the clear mapping of the database environment. Read: documentation. In this blog, Harry Splinter outlines a few practical focal points.

Clear documentation

If we are talking about a standard "Next, next, finish" application that has no other dependencies or specific settings, the manual provided is often sufficient. No one will argue about that. But unfortunately, practice is often a little different. Complex (database) environments are more than enough, as many of us have experienced. Then it is really nice to have clear documentation.

Importance of clear documentation

But what is that, clear documentation? Personally, I assume that documentation should be readable, understandable and executable for a colleague with domain knowledge. Describing how to compose a query or how to install and configure a product, others have already done that. Even basic knowledge is nonsensical to describe. It is mainly the deviations from the standard that we want to capture. There are of course exceptions such as username and passwords, which we don't want in the documentation, public or otherwise. A reference to where these can be found does. The same goes for source citations, a link is sufficient.

Knowledge Sharing

Documentation also makes sense when talking about knowledge sharing. By sharing knowledge or experiences with your colleagues, you help develop the department or company. Because knowledge sharing can also be useful outside the department. Take, for example, a new feature in SQL code. Both for database administrators and developers, a described application plus example is of great value.

Under pressure

We also assume that documentation sometimes needs to be used under pressure. What makes sense can sometimes lead to errors under pressure. As an example, we refer back a previous blog on database recovery. If the documentation is incorrect or inadequately checked and tested, stress rises unnecessarily.

Addition

In addition to descriptions, you also provide any examples, accompanying images and architectural plates for insight on an environment. Other things to consider include findability, searchability, structure, language (do you use English or write documentation in another language), standards (templates), cross-references, data sensitivity (GDPR) and accessibility (centralization).

Review and test!

And once the documentation is in place ... a review takes place. Get documentation checked. What often makes sense to the writer may not make sense to someone else at all. Also test described procedures and code to make sure they are correct.

Tooling and features

Most of the above features can be found in tools, such as online documentation applications, wikis or documents (pdf, word, e-pub), each with their advantages and disadvantages.

Confluence

At OptimaData, we work with one of the best-known online documentation tools with various plug-ins: Confluence. A clear subdivision of clients and chapters provide a clear overview, taking into account the authorization scheme. Dynamic architecture sheets, as shown in the image below, are included, as well as sample code and screenshots. You can also find meeting reports and daily blogs centralized here so that everyone, with the appropriate authorization, contributes to each other's knowledge.

Want to know more?

Would you also like to bring (more) structure to your database management? Did you know that the alignment and professionalization of your documentation is also an area where we can support you? Please feel free to contact us. We would love to get to know you.

back to blogoverview