Use case for Azimutt: Documenting your database

• Why is documentation so hard?
• What can Azimutt do about it?
• A practical example
• Pushing even further

Why is documentation so hard?

As far as I can remember I always heard people complain about documentation. Either because they don't want to write it, they don't know what to put inside or how to structure it. Either because it doesn't exist, they can't find it, it's outdated, or it doesn't cover needed topics.

Very few people can see some gratification in writing documentation, sometimes because it's just a side-contribution in their job, but probably also because the benefit of it is delayed (multiple months later) or even unknown (who and how much it benefited to). One exception is teams doing support, they leverage documentation to decrease their load. But for engineers, we often see this as a necessary task but without much value. And so we don't do it or do it badly.

If you have found a useful piece of documentation recently, please take a few minutes to thank the author. This will be much appreciated 🤩

What can Azimutt do about it?

Obviously, Azimutt won't write a good documentation for you. But it has a few features which should make this much easier for you when doing so, for your database. I believe that good documentation should be contextual: it gives the relevant information in the relevant way at the relevant place.

And what's better than documenting your database tables and columns just on them? For this, Azimutt displays SQL comments and provides an additional notes feature. So if you already have documented your database with SQL comments, you will see them in Azimutt, and they will be formatted using markdown, in case you used it. Otherwise, notes are best as you can see and edit them directly inside Azimutt, making your documentation well alive and easily up to date. You can easily explain in details the use cases of tables and columns as well as how they should be used or what is important to take care of. It's also a very good place to explain your vocabulary or conventions.

But sometimes, you may need to explain things broader than just a column or table. That's why Azimutt also has memos. They are markdown texts in layouts you can place anywhere. This is a great way to create some visual documentation, exploiting markdown capabilities:

• use images for your logo, add highlights like arrows or some illustrations.
• use links for referencing other documentation or any relevant web page.
• use code and tables to give sample queries and show example results.
• use lists for TODOs or assign owners
• use memo color as convention, for feedback, ideas or improvements

You can read more about them in our detailed blog post but clearly they are a game changer for database documentation.

Layouts are also great for documenting. You can create dedicated layouts for explaining different parts of your database, showing only relevant tables and columns and highlighting what's important with memos. If an image is worth a thousand words, a good diagram also can be a powerful game changer. Use them to illustrate your words but also use cases, features or even team scope. Use a naming convention to keep them well organized, and you will be in a very good position to use your database the most efficiently.

Last but not least, embedding your Azimutt diagrams will bring them everywhere, in the best possible context. The embed has recently been augmented by private links, allowing you to create a token to share your diagram with anyone, and so the embed window. If you already have some online documentation, for example in confluence, notion or even docusaurus, it will be a great addition to add rich and interactive database diagrams.

A practical example

Here is a live example of an embedded diagram using a private link. It has some notes and memos but no SQL comment.

Pushing even further

I believe with all this you are already quite well-equipped to document your database without too much trouble. Still a few improvements are planned and could be prioritized according to customer needs.

First, updating SQL comments for sources with a database connection. This would make documentation sharing between tools much easier. But beware, updating a database if far from a trivial operation and I would advise to think twice before activating this once it's available.

Second, adding tags to tables and columns could allow you to categorize and filter them.

Also, adding some documentation history with author and dates to notes and memos will make them more relevant for projects on the long term or with many people.

That's the obvious we have in mind but feel free to suggest other ideas to improve database documentation in Azimutt, even if probably not the most attractive feature to start, we believe this is an important and valuable one (and also one that is not solved at all for now 😉).