Creating documentation standards for column descriptions

Creating documentation standards for column descriptions

Join the Weekly Digest

🤓 Why?

One of the biggest mistakes teams make when rolling out a tool for data documentation is forgetting to establish team standards for what great documentation looks like. If you don't establish high quality documentation standards at the start of a documentation sprint, it's likely that different people will document your data assets in their own unique ways.

‼️ This will make understanding your data assets difficult for your different end users, and it will ultimately result in a "clean-up" sprint.

Wouldn't it be awesome if your team got it right the first time?

To solve this challenge, some amazing DataOps champions started experimenting with ways to create documentation standards that could be followed by different team members.

🌟 What are documentation standards?

Documentation standards are a series of guidelines that your team can follow to create high quality documentation.

Your goal with your team's documentation standards should be that with very little training, a new joinee can read your standards and start documenting like a pro. 😎

♥️ Best practices from the community

The team at TechStyle created some amazing column description standards that can serve as inspiration for data teams around the world.

Snapshot of Techstyle's documentation standards for their modern data warehouse rollout
Snapshot of Techstyle's documentation standards for their modern data warehouse rollout

You'll see that TechStyle's documentation standards include both broad hygiene parameters as well as specific standards for common fields in their data warehouse.

For example, here are a few of their basic rules:

  • All documentation should be grammatically correct
  • The first letter of a column description should always be capitalized.

It could also include very specific standards that are specific to your data and its common fields. Here's an example:

  • Fields with suffix "_ID" should be documented as "Primary Key Natural" + "Foreign Key Natural" + "Business Description".

🤙 TL;DR: Creating your own documentation standards

1️⃣ Start with an initial prototype (or MVP) and a decentralized documentation approach.

  • Choose an MVP: Roll out a data governance and documentation tool (Atlan) for one use case.
  • Test a few cases: Choose a few easy tables and ask team members to document them.

2️⃣ Organize a workshop with the team.

In this workshop, the team can compare documentation approaches, learn best practices, and create common documentation standards.

  • Review the documentation done for your initial test cases as a team.
  • Assign a note-taker who documents the team's feedback and decisions.
    • Note positive feedback in a "Do's" section of your common documentation framework.
    • Note negative feedback in a "Don'ts" section of your common documentation framework.
    • Note any ideas and challenges as they come along.
  • Discuss the outcome of the documentation review as a team, and note the final decisions in a final "Documentation Standards" document.

3️⃣ Sprint and refine.

Carry out a series of sprints to continue building new documentation for other tables and columns for your use case, all while refining the documentation standards.

You can also meet as a team on a weekly or fortnightly basis to run a "Do's/Don'ts" exercise and refine the standards.

4️⃣ Assign one or more "approvers".

These people should be responsible for reviewing the documentation to ensure standards are being met.

🔗 Related reads