From 01a7bd9685d501d9f0849f4db432daac6a7216a4 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Mon, 13 Jul 2026 14:15:20 +0200 Subject: [PATCH] docs: standardize and simplify how data-dict is described --- AGENTS.md | 2 +- README.md | 8 +++----- site/_quarto.yml | 6 +++--- site/index.md | 2 +- 4 files changed, 8 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 58603d2..27fae20 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # data-dict.yaml -`data-dict.yaml` is a YAML-based data dictionary specification and validator. It describes collections of related tables — their columns, types, constraints, relationships, and domain vocabulary — and is designed to be co-written by humans and AI agents. The main deliverable is a CLI tool that validates data dictionary YAML files against the spec. +`data-dict.yaml` is a lightweight, YAML-based data dictionary specification for describing collections of related tables — their columns, types, constraints, relationships, and domain vocabulary. The main deliverable is a CLI tool that validates data dictionary YAML files against the spec. The repo contains: diff --git a/README.md b/README.md index 057b595..299d730 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,8 @@ # `data-dict.yaml` -`data-dict.yaml` is a lightweight, YAML-based data dictionary specification. It -describes a collection of related tables — their columns, types, constraints, -relationships, and the domain vocabulary you need to understand them — in a -single file that humans and AI agents can co-author and keep in sync with your -data. +`data-dict.yaml` is a lightweight, YAML-based data dictionary specification for +describing collections of related tables — their columns, types, constraints, +relationships, and domain vocabulary. **Full documentation, including the detailed specification, lives at [data-dict.tidyverse.org](https://data-dict.tidyverse.org).** diff --git a/site/_quarto.yml b/site/_quarto.yml index 8a55466..1add5ec 100644 --- a/site/_quarto.yml +++ b/site/_quarto.yml @@ -9,9 +9,9 @@ website: site-url: https://data-dict.tidyverse.org repo-url: https://github.com/tidyverse/data-dict description: > - A YAML-based data dictionary specification for describing collections of - related tables — their columns, types, constraints, relationships, and - domain vocabulary. + A lightweight, YAML-based data dictionary specification for describing + collections of related tables — their columns, types, constraints, + relationships, and domain vocabulary. llms-txt: true navbar: left: diff --git a/site/index.md b/site/index.md index acc0ad6..4783e0f 100644 --- a/site/index.md +++ b/site/index.md @@ -2,7 +2,7 @@ title: "data-dict.yaml" --- -`data-dict.yaml` is a data dictionary specification that describes a collection of related tables: their contents, constraints, connections, and the specialised vocabulary you need to understand them. It is designed to be a living document, co-written by humans and agents, that tracks your understanding of a dataset as it evolves. +`data-dict.yaml` is a data dictionary specification that describes a collection of related tables: their contents, constraints, connections, and the specialised vocabulary you need to understand them. It is designed to be a living document that tracks your understanding of a dataset as it evolves. `data-dict.yaml` is designed to be lightweight. It doesn't attempt to precisely describe every possible type of metadata in a machine-readable way. Instead it focuses on precisely recording the most important components, leaving the remainder to plain text fields that require a human or agent to interpret. This means that `data-dict.yaml` doesn't itself do **data cleaning**, but it is a useful complement to tools that do.