Analytics documentation is operating infrastructure for decisions. It tells a reader what a dataset or metric means, where it came from, how current it is, who owns it, which uses are supported and what to do when it fails. A catalog full of generated column names is not enough. Documentation earns trust when it appears in the workflow, changes with the data product and shortens investigation without asking readers to locate the original author.
This playbook focuses documentation effort on consequential assets and recurring questions. Pair it with the data contracts engineering notes for producer-consumer change agreements, the dbt models guide for transformation ownership and the founder dashboard guide for decision-facing presentation.
1. Inventory questions, not pages
Start with the assets that support financial, customer, product or operational decisions and the questions people ask about them. Which table should I use? What does active mean? Why did yesterday change? Can this field identify a person? Who approves a new exclusion? Observe support channels, review meetings, incidents and repeated query comments. Rank documentation by decision consequence, audience size, change rate and current confusion.
Assign a business steward and technical owner. The steward approves meaning and intended use; the technical owner maintains implementation, tests and service behavior. A platform team can provide templates and automation but cannot infer business authority. Define review triggers such as schema change, source migration, metric revision, incident, ownership change and scheduled renewal. Avoid treating a once-a-year documentation campaign as maintenance.
| Asset | Minimum reader promise | Owner |
|---|---|---|
| Source dataset | Origin, scope, sensitivity, update and known limits | Source owner |
| Warehouse model | Grain, keys, transformation, tests and consumers | Analytics engineer |
| Metric | Population, formula, time, dimensions and decision | Business steward |
| Dashboard | Audience, decisions, freshness and drill path | Product or analytics owner |
| Pipeline | Inputs, outputs, schedule, failure and recovery | Data platform owner |
| Experiment | Hypothesis, assignment, exclusions and analysis state | Experiment owner |
2. Use templates that expose decisions
A useful dataset page includes purpose, grain, keys, field meaning, source, update behavior, quality expectations, access classification, lineage, examples, owner, support route and known limitations. A metric page adds eligible population, formula, timestamps, exclusions, dimensions, comparison behavior and change history. Put the definition beside the query or chart where possible. Readers should not need to open five systems to learn whether a value is provisional.
Write examples and counterexamples. Show a record that qualifies, one that does not and an awkward case such as a refund, late event or ownership transfer. Use plain language before implementation details. Link executable logic rather than pasting an unmaintained copy. The official dbt documentation guidance describes descriptions, lineage and generated project documentation; teams still need an ownership process for the business meaning those features publish.
3. Combine automated lineage with human context
Automate stable technical facts: schemas, tests, jobs, runs, code locations and upstream or downstream relationships. The OpenLineage object model represents jobs, runs and datasets with extensible facets. Use it or an equivalent event model to capture execution lineage, then add why the dependency matters, which consumer decision is affected and who owns remediation. A graph of nodes cannot explain a business exclusion.
The W3C PROV overview describes provenance through entities, activities and agents and provides a family of interchange specifications. That distinction is practical: a table is an entity, a transformation run is an activity and a team or service can bear responsibility. Preserve versions and run context so investigators can explain which inputs and process produced a result, not merely which table usually feeds it.
4. Publish discovery without leaking access
Make approved assets searchable by business term, domain, owner, status, sensitivity and supported use. W3C DCAT 3 distinguishes datasets, distributions, data services, versions and series for interoperable catalogs. An internal catalog can borrow that clarity even without RDF: describe the conceptual asset separately from a file, table or API that distributes it, and make superseded versions visible.
Discovery permission and data permission are different. A restricted reader may benefit from knowing an asset exists, who owns it and how to request access without seeing sensitive schema, samples or profiles. Classify documentation fields, redact examples, and test search indexes, generated previews and lineage for indirect disclosure. Keep access decisions in the authoritative control system rather than assuming a documentation label enforces them.
| Documentation check | Failure signal | Operating response |
|---|---|---|
| Freshness | Page describes an old schedule or source | Trigger review from deployment metadata |
| Ownership | Contact left or team changed | Route through domain ownership register |
| Meaning | Readers repeatedly ask the same definition | Rewrite with example and counterexample |
| Lineage | Impact analysis misses a consumer | Repair instrumentation and add declared dependency |
| Access | Preview exposes sensitive values | Disable preview and review indexing policy |
| Use | Asset has no supported consumers | Archive with history and redirect |
5. Document change before release
Classify changes by compatibility. Additive fields may still alter wildcard queries; renamed values may break business logic; changed metric populations can create false trends. Publish the reason, effective date, affected assets, comparison impact, migration steps, owner and retirement date. Link the change to tests and code review. For high-impact definitions, give known consumers a comparison window and preserve both versions only as long as the migration requires.
Use data contracts to state producer and consumer expectations for schema, semantics, timing, quality, access and notification. The contract is not a substitute for discussion; it makes the agreed boundary testable. Record exceptions with owners and expiry. When an upstream team cannot guarantee a field, document the downstream fallback and visible degraded state instead of silently converting missing input into zero or an old value.
6. Make documentation part of operations
During an incident, show affected datasets and decisions, current status, data cutoff, workaround, owner and next update. Do not overwrite the normal definition with temporary incident prose; link a time-bounded status record. After recovery, update limitations, runbooks, lineage and tests based on the confirmed cause. A post-incident action to 'improve docs' should name the exact question that responders or consumers could not answer.
Monitor the documentation service and generation path. OpenTelemetry signals can help correlate traces, metrics and logs for search, rendering and metadata ingestion. More importantly, measure operational outcomes: time to find an owner, repeated support questions, stale-page reports, change-notice reach, incident investigation time and undocumented high-use assets. Traffic alone may indicate confusion rather than value.
Run quarterly renewal by domain. Review high-use and high-risk assets, stale ownership, failed links, unresolved limitations, duplicate definitions and assets with no supported consumer. Archive deliberately, preserving definition and replacement route. Make contribution easy through repository templates or catalog forms, but require review for consequential meaning. Automation should open focused maintenance work, not generate paragraphs nobody owns.
7. Put documentation inside daily work
Add documentation checks to pull requests and deployments. A changed model should prompt review of descriptions, owners, tests, examples, classifications and downstream notices. Keep checks focused: requiring text for every temporary field encourages meaningless completion. Consequential assets deserve stronger gates, while exploratory work can use a lightweight status and expiry. Promotion to a shared product should trigger the complete template and steward review.
Bring definitions into the places where readers decide: metric tooltips, dashboard details, query editors, incident notices and review agendas. Link back to the maintained source for depth. Capture feedback with page and asset context so the owner can reproduce the ambiguity. Search terms that return no result and repeated support questions are useful backlog evidence when they are reviewed by domain owners rather than accumulated as platform analytics.
Train through real questions. Ask a new analyst to identify the correct dataset, explain its grain, find a restricted field owner, trace a late result and determine whether a metric change affects a dashboard. Record where they stall and repair the workflow. Documentation quality is demonstrated by successful use under ordinary permissions, not by the number of generated pages or completion percentage.
Define an escalation route for contested meaning. The technical owner should preserve evidence and alternatives, while the business steward decides the supported definition or names separate variants. Publish the decision and effective date. Leaving a dispute in chat invites each consumer to encode a private resolution and multiplies future reconciliation.
Preserve rejected alternatives when they explain an important boundary. A short decision record can prevent the same debate from recurring after staff change and gives future owners evidence to revisit the choice when business conditions differ.
Key takeaways
- Prioritize recurring decision questions and consequential assets before broad catalog coverage.
- Assign business meaning and technical operation to explicit, complementary owners.
- Combine generated lineage with examples, limitations and decision context.
- Separate asset discovery from permission to inspect data and metadata.
- Publish material changes, comparison impact and migration before release.
- Use incidents, support questions and renewal evidence to maintain or retire documentation.
Analytics documentation FAQ
Should documentation live beside code or in a catalog? Keep executable and technical facts close to code, then publish them into a discovery experience that can add business context. Link rather than duplicate.
Can AI write analytics documentation? It can draft from code and metadata, but an accountable owner must verify meaning, supported use, sensitivity and limitations before publication.
How often should pages be reviewed? Trigger review on material change and incidents, with a risk-based scheduled renewal. High-change, consequential assets need more frequent attention.
What should be documented first? Start with the metric or dataset that repeatedly delays an important decision, then capture its definition, source, timing, owner, limitations and change path.
Conclusion: operate documentation as evidence
Analytics documentation becomes dependable when it is owned, testable and connected to change. Document the decisions people make, automate technical facts, preserve provenance, protect sensitive metadata and learn from incidents. A smaller maintained collection is more valuable than a comprehensive catalog whose readers cannot tell what is current.