Define standards for descriptions

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.

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 team member can read your standards and start documenting like a pro.

Create your own documentation standards

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.

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 the following in your common documentation framework:
  • Positive feedback in a Do section.
  • Negative feedback in a Don't section.
  • 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.

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/Don't exercise and refine the standards.

Assign one or more approvers

The approvers should be responsible for reviewing the documentation to ensure standards are being met.

Example from the community

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

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".

Read the full story of how TechStyle rolled out their documentation standards using Agile sprints.