A reusable markdown framework for documenting Power BI semantic models and reporting assets. It provides a consistent structure for model context, tables, measures, relationships, refresh details, and handover notes without requiring any specific tool or platform.
- Power BI developers documenting their own models
- BI analysts maintaining shared reporting assets
- Analytics engineers working across multiple semantic models
- Consultants delivering models and reports to clients or internal teams
- Reporting teams that need traceability, governance, and faster handovers
If you are starting from scratch, begin with these five files:
model-overview.mdtable-inventory.mdmeasure-catalog.mdrelationship-map.mdrelease-notes.md
That set is enough to explain what the model is for, how it is structured, what it calculates, how tables connect, and how the model has changed over time.
Example: a support operations model with one fact table and six dimensions.
- Document the model purpose and audience in
model-overview.md. - List
FactTicket,DimAssignee, and the other tables intable-inventory.md. - Capture measures such as
Total TicketsandSLA Compliance %inmeasure-catalog.md. - Record the active
FactTicket[OpenDateKey] -> DimDate[DateKey]relationship inrelationship-map.md. - Add an initial
v1.0 - Initial documentationentry inrelease-notes.md.
The worked example in examples/support-operations-analytics/ shows the full set filled in end to end.
- 14 reusable markdown templates covering model overview, tables, columns, measures, relationships, Power Query, reports, KPIs, business glossary, refresh/deployment, handovers, decisions, and release notes
- A complete worked example using a generic Support Operations Analytics model
- 8 practical guides covering setup, maintenance, adaptation, and examples
- Optional Claude Code support through project instructions and reusable skills
The framework is plain markdown. It works with any editor, any repository host, and any workflow.
powerbi-model-docs-framework/
|-- templates/
| |-- model-overview.md
| |-- source-inventory.md
| |-- table-inventory.md
| |-- column-dictionary.md
| |-- measure-catalog.md
| |-- relationship-map.md
| |-- power-query-docs.md
| |-- report-page-inventory.md
| |-- kpi-definition.md
| |-- business-glossary.md
| |-- refresh-deployment-notes.md
| |-- handover-summary.md
| |-- issue-decision-log.md
| `-- release-notes.md
|-- examples/
| `-- support-operations-analytics/
|-- guides/
| |-- getting-started.md
| |-- documenting-a-new-model.md
| |-- keeping-docs-updated.md
| |-- using-the-examples.md
| |-- adapting-the-framework.md
| |-- claude-code-integration.md
| |-- best-practices.md
| `-- maintaining-the-framework.md
|-- .claude/
| `-- skills/
|-- CLAUDE.md
|-- CONTRIBUTING.md
|-- CODE_OF_CONDUCT.md
|-- CHANGELOG.md
|-- ROADMAP.md
|-- PROJECT_SCOPE.md
`-- LICENSE
- Clone or download this repository.
- Copy the templates you need into your project's documentation folder.
- Start with the minimum starter set.
- Fill in the templates and remove the instructional blockquotes.
- Add more templates as the model and reporting estate become more complex.
See guides/getting-started.md for a detailed walkthrough.
| Template | Purpose |
|---|---|
| model-overview | High-level summary of the semantic model |
| source-inventory | Data sources feeding the model |
| table-inventory | All tables with type, grain, and row counts |
| column-dictionary | Column-level definitions and data types |
| measure-catalog | All measures with DAX, descriptions, and business context |
| relationship-map | Table relationships and cardinality |
| power-query-docs | Power Query transformation logic |
| report-page-inventory | Report pages and their purpose |
| kpi-definition | KPI definitions with targets and thresholds |
| business-glossary | Shared business terms and definitions |
| refresh-deployment-notes | Refresh schedules and deployment details |
| handover-summary | Context for team transitions and handovers |
| issue-decision-log | Design decisions and open issues |
| release-notes | Version history and change log |
The examples/support-operations-analytics/ folder contains every template filled in for a fictional support ticket reporting model. It demonstrates:
- A star schema with 1 fact table and 6 dimensions
- 12 measures covering volume, SLA, satisfaction, backlog, and productivity
- 5 KPIs with targets and thresholds
- A business glossary with 14 defined terms
- A complete decision log and release history
Use it as a reference for structure and level of detail.
- New model setup
- Existing model documentation audit
- Team handover
- Governance and traceability
- Consulting delivery
- Analyst and developer onboarding
If you use Claude Code, this repository includes:
- A project-level
CLAUDE.mdwith repo context, style rules, and public-safety guidance - 6 reusable skills for common documentation workflows
| Skill | Purpose |
|---|---|
create-model-docs | Scaffold a full documentation set from templates |
review-documentation | Review docs against framework standards and flag gaps |
generate-measure-catalog-entry | Create a measure entry from a DAX expression |
update-release-notes | Append a formatted release entry |
validate-completeness | Check for missing or incomplete templates |
create-template-from-pattern | Turn a recurring pattern into a new template |
Claude Code support is optional. The framework is fully usable without it. See guides/claude-code-integration.md for setup details.
This framework is designed to work well with AI-assisted development tools such as Claude Code.
Claude can help automate parts of the documentation workflow, including:
• generating measure catalog entries from DAX expressions
• reviewing model documentation for completeness
• scaffolding documentation templates for new semantic models
• validating that required documentation files exist in a project
The repository includes example Claude Code skills that demonstrate how AI can support consistent analytics documentation while keeping humans in control of the documentation process.
The goal is to combine structured documentation practices with AI-assisted workflows to make maintaining BI model documentation easier and more reliable.
Contributions are welcome. See CONTRIBUTING.md for guidelines.
Good first contributions:
- Improve template field descriptions
- Add an example for a different domain
- Write a guide for a specific documentation workflow
- Fix typos or broken links
See ROADMAP.md for the full plan. Near-term items include:
- RLS documentation template
- Data lineage / source-to-target mapping template
- Additional worked examples for different domains
- Model review checklist
- Metadata extraction helpers
MIT. See LICENSE.