How to document

How it generally works

Publishing documentation is tied directly to pushing a new git commit. If you change the relevant dbt .yml files, or add/edit markdown files related to a given query, these docs will auto-update when you push to remote.

dbt (/dbt)

These are populated directly from the _models.yml and _sources.yml files in the dbt/models/ directory. No extra work needed here!

Queries (/queries)

Each query should have it's own directory with both the relevant sql file and a corresponding .md file.

If you have a group of queries that are all closely related, then they can all live in a single directory and share a single .md file.

To keep navigation legible and easy, we further organize queries into various themes. The first one we've created as an example is engagaement_and_usage, but we may need to either narrow or widen the scope of how we think of taxonomy.

Example:

engagaement_and_usage
├── query_or_group_of_related_queries
    ├── query_one.sql
    ├── query_two.sql
    ├── query_or_group_name.md

In each markdown file, it's best practice to include the text of the query itself. Instead of copying and pasting, you can dynamically insert query code by adding the following in your markdown:

```sql
--8<-- "queries/path/to/query.sql"
```

Replace the path with the correct path relative to the repo root.

All .md files in the queries/ directory must start with front matter as follows in order to properly be turned into a Hex guide:

---
name: Query Name
description: A brief description of the query
---

All .md files in the queries/ directory will be crawled and automatically added to the documentation, so no need to add them to a .pages file or anything.

Hex guides

Query documentation is also automatically published as guides to Hex, giving Hex's AI context about our queries. This happens via a GitHub Action on merge to main — no extra steps needed. The --8<-- snippet directives are resolved before upload, so Hex receives the full SQL text.

The front matter (name and description) is what Hex uses to identify and describe each guide, so make sure those fields are clear and descriptive.