How to Craft Meaningful Data Documentation

Welcome to chapter 4 of our “Data Documentation Demystified” series, where we delve deeper into the intricate world of data documentation. In our previous articles, we covered the importance of documentation, its various forms, and the process of setting up a framework for it.

However, the most critical aspect of documentation remains to be uncovered - how to actually write documentation. Crafting descriptions that capture the essence of your data is no small feat, and it's a skill that can take time to develop.

Luckily, we're here to help. In this article, we'll be sharing three essential pieces of advice to help you create documentation that truly captures the essence of your data. We’ll be covering three

From avoiding obvious statements to the power of a single image, we'll guide you through the process of creating documentation that is both concise and informative. So, let's get started and take your documentation to the next level.

I. Obvious statements = Pollution

It can be tempting to resort to writing obvious statements in order to quickly complete the documentation process. However, this is not a viable approach, especially when it comes to documenting a data warehouse. Setting the right documentation standards is crucial, particularly if you aim to crowdsource data documentation. Therefore, it's important to avoid pollution statements that don't add any meaningful value to the documentation.

One effective way to tackle documentation, as used by Stuart, is to have a small team start documenting tables in an exceptional manner. This will serve as an example for the rest of the company to follow, and eventually everyone can contribute to building a robust knowledge framework. By doing so, the company can crowdsource documentation and accelerate the transition towards a decentralized data infrastructure.

How do you differentiate between obvious statements and meaningful documentation? Here are a few examples:

‍

II. A picture is worth a thousand words

Sometimes words alone are not enough to convey the necessary information. That's where pictures come in. Screenshots, charts, and diagrams can be powerful tools for communicating complex ideas in a more accessible and user-friendly way.

‍

Screenshots

Screenshots are especially useful when the data comes from an application or a website. With screenshots, users can easily visualize the data and better understand how it fits into the context of the application or website.

For instance, consider the example of documenting tables from Facebook campaign data. Instead of providing a lengthy description of the campaign form, taking a screenshot of the form and including it in the documentation can be a more efficient and effective way of communicating the necessary information. The screenshot allows the user to see exactly what the campaign form looks like and where to input the relevant data, making it easier for them to understand how to work with the form and what data is required. Overall, including screenshots in data documentation can make it more accessible, user-friendly, and enhance its overall effectiveness.

‍

Charts & Diagrams

In addition to screenshots, charts and diagrams can be another effective way of documenting data. Charts can be used to represent data visually and help users quickly understand patterns and trends. Diagrams, on the other hand, are ideal for representing complex relationships and concepts in a simplified way.

Using a tool like Mermaid can make it easy to create diagrams that are both informative and visually appealing. Mermaid's markdown language is intuitive, and it offers a range of diagram types, including entity relationship diagrams (ERDs). This makes it easier to keep track of changes and update diagrams as needed.

For charts, Whimsical is a great tool that allows users to embed their charts directly into documentation. This makes it easy for users to access the information they need without having to switch between different applications. Overall, using charts and diagrams can be a great way to enhance the accessibility and usability of data documentation.

‍

III. Don’t repeat yourself

When it comes to documenting data, it's important to remember a few key principles. For starters, the principle of "Don't repeat yourself" (DRY) is an important one to keep in mind. This means that you shouldn't include the same information multiple times throughout your documentation. Instead, focus on providing clear, concise explanations that get the point across directly.

Another important principle to keep in mind is to avoid adding too many details. While it can be tempting to include every little piece of information about a particular topic, this can actually make your documentation harder to read and understand. Instead, focus on providing the necessary details in a clear, concise manner.

It's also a good idea to move common knowledge to a dedicated page, rather than copying and pasting it throughout your documentation. This can help to streamline your content and make it easier to read and understand.

Finally, it's worth noting that examples are generally more useful than long explanations. Whenever possible, include real-world examples that illustrate the concepts you're discussing. This can help to make your documentation more engaging and relevant.

Final words

In this piece, we've covered three essential guidelines for creating impactful data documentation. These include not stating the obvious, leveraging visual aids to convey ideas effectively, and avoiding repetition.

Receive the next chapter about where documentation should live directly in your inbox.

Subscribe to the newsletter

About us

We write about all the processes involved when leveraging data assets: from the modern data stack to data teams composition, to data governance. Our blog covers the technical and the less technical aspects of creating tangible value from data.

At Castor, we are building a data documentation tool for the Notion, Figma, Slack generation.

Or data-wise for the Fivetran, Looker, Snowflake, DBT aficionados. We designed our catalog software to be easy to use, delightful and friendly.

Want to check it out? Reach out to us and we will show you a demo.

‍

‍