Documentation

dex allows you to add human-readable descriptions to your data models, columns, and tests. This metadata helps your team understand what each object in your project represents—improving collaboration, onboarding, and trust in your data assets.

Well-documented models create clarity for both technical and non-technical stakeholders. By keeping documentation close to your transformation logic, you ensure that knowledge stays version-controlled, discoverable, and always up-to-date.

How Documentation Works

In dex, documentation is stored directly in the same .yml files used to define tests and register models. This ensures your model logic and your documentation stay tightly coupled.

You can document:

• Models: What the table represents

• Columns: What each field means and how it should be interpreted

• Tests: Why a test exists and what it’s validating

Once defined, documentation is surfaced across dex:

• In the Develop section alongside your code

• In the Lineage and Data Catalog views

• In model previews, helping you interpret the outputs

Adding Descriptions to Models and Columns

To document a model, create or open the corresponding .yml file in the same folder where your model resides. Use the description field for both models and their columns.

Example

version: 2

models:
  - name: customers
    description: "A dimension table containing one row per unique customer, including demographic and location data."
    columns:
      - name: customer_id
        description: "Unique identifier for each customer. Used as the primary key."
        tests:
          - not_null
          - unique

      - name: customer_type
        description: "Business logic-driven classification such as 'new', 'returning', or 'VIP'."

Where Documentation Appears in dex

dex automatically renders your documentation across multiple views in the platform:

• Model Explorer: View model-level and column-level descriptions inline while browsing or editing.

• Data Lineage View: See descriptions alongside dependencies and impact graphs.

• Catalog: Search and browse datasets with their documented context.

• Preview Pane: Get field-level tooltips when inspecting query outputs.

This makes documentation immediately accessible for anyone interacting with your models—without needing to open the YAML file directly.

Best Practices

• Be clear and concise: A good description helps someone unfamiliar with the model understand its purpose.

• Keep it updated: Documentation should evolve with your models. If logic changes, update the description as part of the same commit.

• Use business terms: When possible, write descriptions in plain language that aligns with how your business talks about data.

• Describe intent, not just structure: For example, instead of “customer_type: the type of customer,” say “customer_type: Business logic-driven classification such as 'new', 'returning', or 'VIP'.”