Why this matters
As an Analytics Engineer, your transformations, models, and dashboards evolve constantly. If docs fall behind the code, teammates ship wrong queries, dashboards mislead, and audits fail. Keeping documentation in sync ensures trustworthy analytics, faster onboarding, and smoother reviews.
- Real tasks: add a column to a model, deprecate a field, fix a metric bug, migrate a table, or change SLOs. Each change needs a matching doc update.
- Outcome: less ambiguity, fewer Slack pings, and more reliable BI.
Note: The quick test below is available to everyone; only logged-in users will have saved progress.
Concept explained simply
Docs-as-code means documentation lives next to the code, changes together with it, and is reviewed like code. Treat documentation as part of the commit, not an afterthought.
Mental model
Think in pairs: for every code change, there is a matching doc change. If you cannot point to the doc update, the change is not done. Code and docs move together like two shoes; shipping one without the other makes you stumble.
Minimum setup that works
- Keep docs in the same repository as transformations and models.
- Adopt a definition of done that includes docs updated.
- Use a pull request template with a checklist for docs and release notes.
- Write model-level YAML or similar schema files with descriptions, data types, tests, and owners.
- Maintain a CHANGELOG and migration notes for breaking changes.
- Automate a docs-lint step to catch missing descriptions and owners.
Worked examples
Example 1: Add a new column to a fact model
Scenario: You add column customer_lifetime_value_usd to fct_orders.
- Update the model schema file with a clear description and type.
- Add tests or constraints if relevant (non-negative, nullable policy).
- Update the model README describing the new insight unlocked.
- Add a line to the CHANGELOG under Added.
# models/fct_orders.yml
models:
- name: fct_orders
description: Fact table of orders with revenue and customer metrics
columns:
- name: customer_lifetime_value_usd
description: Estimated lifetime value for the order's customer in USD
data_type: numeric
constraints: non_negative, nullable
owner: analytics
# CHANGELOG
## Added
- fct_orders: customer_lifetime_value_usd (numeric). Helps LTV segmentation.
Example 2: Rename a column (breaking change)
Scenario: Rename user_id to account_id.
- Mark user_id as deprecated for one release and document the replacement.
- Update schema file to add account_id with description and type.
- Add migration notes describing what to change in downstream queries.
- Record the change in CHANGELOG under Breaking with a timeline.
# models/fct_events.yml
models:
- name: fct_events
columns:
- name: account_id
description: Primary account identifier; replaces user_id
data_type: string
owner: analytics
- name: user_id
description: Deprecated; will be removed next release
deprecated: true
# MIGRATIONS
Replace user_id with account_id in joins and filters.
# CHANGELOG
## Breaking
- fct_events: user_id deprecated; use account_id. Removal planned next release.
Example 3: Correct a metric bug
Scenario: revenue previously excluded refunds.
- Describe the fix in the model description: revenue now net of refunds.
- Add a test or note on calculation logic and known limitations.
- Document the effective date to help analysts compare historical numbers.
# models/fct_orders.yml (snippet)
- name: revenue
description: Net revenue (gross minus refunds) effective 2025-02-01
# CHANGELOG
## Fixed
- fct_orders: revenue now subtracts refunds (effective 2025-02-01).
Workflow templates you can copy
Pull request template
Title: Model change: <component>
Summary:
- What changed
- Why it changed
Doc checklist:
- [ ] Schema updated (columns, types, descriptions, owners)
- [ ] README updated (purpose, logic, caveats)
- [ ] CHANGELOG entry added (Added/Changed/Fixed/Breaking)
- [ ] Migration notes written if breaking
- [ ] Tests updated
Definition of done
- Code merged with passing tests
- Schema and descriptions updated
- Owners and data quality notes present
- Release note or changelog entry added
- Migration guidance written for any breaking change
Architecture decision record (ADR) outline
Context
Decision
Alternatives considered
Consequences (trade-offs)
Date and owner
Automation ideas
- Docs coverage check: fail builds when columns lack descriptions or owners.
- Deprecated flag check: warn when deprecated items linger beyond the window.
- Changelog presence: require a release note for any modified model files.
- Consistency check: ensure data type in docs matches model code where possible.
Exercises
Do these now. They mirror the scored exercises below.
Exercise 1: Write the doc updates for a new column
Scenario: Add customer_lifetime_value_usd to fct_orders. Write the schema snippet and a concise changelog entry. Include data type, a one-line description, and whether it can be null.
- Deliverables: schema snippet and one changelog line.
- Timebox: 10 minutes.
Exercise 2: Plan docs for a breaking rename
Scenario: Rename user_id to account_id in fct_events. Produce: deprecation plan, migration notes, and a changelog entry labeled Breaking.
- Deliverables: short deprecation paragraph, migration steps, changelog lines.
- Timebox: 12 minutes.
Exercise checklist
- Descriptions are clear and specific (what, unit, business meaning).
- Types and nullability stated where relevant.
- Owners or contacts present for new or changed data.
- Changelog uses Added, Changed, Fixed, or Breaking consistently.
- Migration guidance exists for any rename or removal.
Common mistakes and how to self-check
- Missing owners: add a team or person for each model and critical column.
- Vague descriptions: include unit, calculation, and caveats.
- No effective date for fixes: state when the new logic applies.
- Silent breaking changes: never rename or remove without deprecation notes.
- Docs live elsewhere: keep docs with the code to avoid drift.
Self-check: If you shipped a change, can a teammate understand what changed, why, when it takes effect, who owns it, and how to migrate? If any answer is no, update the docs.
Practical projects
- Docs coverage dashboard: measure percent of columns with descriptions and owners.
- Release hygiene: add a changelog and ensure every merged PR adds an entry.
- Deprecation policy: create a simple document with timelines and examples.
Next steps
- Who this is for: Analytics Engineers and BI Developers maintaining data models and dashboards.
- Prerequisites: basic SQL, familiarity with version control and schema files.
- Learning path: adopt the PR template, implement the definition of done, then add a docs coverage check.
- Final tip: move small but steady. Update docs in the same commit as the code.
Mini challenge
In two sentences, write a changelog entry for a fix changing revenue to net of refunds and add one migration note for downstream users. Keep it concise.