# 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

```yaml
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'.”


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dexlabs.io/lakehouse-platform/develop-with-dex/documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.