docs: align toolkit terminology with current FinOps Framework naming by MSBrett · Pull Request #2170 · microsoft/finops-toolkit

MSBrett · 2026-06-03T15:01:49Z

Why

The FinOps Foundation renamed several Framework capabilities and domains in its current revision. Two of those names appear throughout the FinOps toolkit's customer-facing surfaces:

Workload optimization is now Usage optimization
Policy and governance is now Governance, policy, and risk

Until now the toolkit still used the old names in its docs, dashboards, workbooks, and Power BI reports. That's a problem because users constantly cross-reference the toolkit against the Framework on finops.org — when a report tile says "Workload optimization" but the Framework calls it "Usage optimization," it's not obvious they're the same capability. This PR brings every toolkit surface back in line with the current Framework vocabulary so the naming is consistent wherever a user looks.

Why it's large

These capability names aren't in one place — they're duplicated across many independent surfaces that all have to stay in lockstep:

Microsoft Learn documentation (Framework pages, toolkit guidance, alerts, optimization engine, help)
The FinOps hubs Data Explorer dashboard (dashboard.json)
The cost optimization workbook
Both Power BI report variants — kql/ and storage/ — including in-report label text and capability links
Build-PowerBI.ps1, which generates the report descriptions baked into the published PBIX files

So a single rename touches ~47 files. The change is mechanical and low-risk, but it has to be applied everywhere at once or the surfaces drift out of sync.

What changed

Terminology alignment

Renamed Workload optimization → Usage optimization and Policy and governance → Governance, policy, and risk across all docs, the dashboard, the workbook, both report variants, and the build script.
Capability/domain labels use sentence case per the repo coding guidelines (for example, "Governance, policy, and risk", "Understand usage and cost").
Framework capability links continue to point to Microsoft Learn (learn.microsoft.com/.../framework/...).

Architecture diagram

Updated finops-hubs-overview/architecture.png to show the additional agent consumers that can query the hub (alongside the existing GitHub Copilot path).

Incidental copy fixes folded in while the lines were open

"This reports uses" → "This report uses"
"shutdown" → "shut down"
"Understand uage and cost" → "Understand usage and cost"
"domain focused" → "domain is focused"
"involve refers to" → "refers to"
Duplicated "As a As a" → "As a"
"Cost management exports" → "Cost Management exports" (product name)
Routed the in-product feedback links to the current survey ID (FTK15.0)

Risk

No behavioral or schema changes — this is documentation, labels, and report description text. The Power BI report changes are limited to display text and capability links; the underlying queries and data model are untouched. JSON report assets were validated to parse, and the changelog records the change under the current release.

Copilot

Pull request overview

Updates FinOps Toolkit documentation and reporting labels to align with the current FinOps Framework naming (for example, “Usage optimization” and “Governance, Policy & Risk”) and refreshes framework links across the toolkit’s docs, dashboards, workbooks, and Power BI report copy.

Changes:

Renames multiple capability/report labels (notably “Workload optimization” → “Usage optimization”, “Policy and governance” → “Governance, Policy & Risk”) across workbook/report assets and docs.
Updates several framework “Learn more” links (notably in the FinOps hubs dashboard markdown cards and Power BI report text) to point to finops.org.
Adds a new site doc page consolidating brand and naming guidance (docs/brand.md).

Reviewed changes

Copilot reviewed 50 out of 51 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/workbooks/optimization/CostOptimization.workbook	Updates workbook group label to “usage optimization”.
src/templates/finops-hub/dashboard.json	Updates domain/capability markdown card titles and framework links (finops.org).
src/scripts/Build-PowerBI.ps1	Updates report intro strings to match new naming.
src/power-bi/storage/WorkloadOptimization.Report/report.json	Updates in-report label text and capability links to “Usage optimization”.
src/power-bi/storage/RateOptimization.Report/report.json	Updates in-report description and capability link targets (finops.org).
src/power-bi/storage/Invoicing.Report/report.json	Updates capability link targets (finops.org).
src/power-bi/storage/Governance.Report/report.json	Updates report name/description to “Governance, Policy & Risk” and capability link targets.
src/power-bi/storage/DataIngestion.Report/report.json	Updates capability link targets (finops.org).
src/power-bi/storage/CostSummary.Report/report.json	Updates capability link targets (finops.org).
src/power-bi/kql/WorkloadOptimization.Report/report.json	Updates in-report label text and capability links to “Usage optimization”.
src/power-bi/kql/RateOptimization.Report/report.json	Updates capability link targets (finops.org).
src/power-bi/kql/Invoicing.Report/report.json	Updates capability link targets (finops.org).
src/power-bi/kql/Governance.Report/report.json	Updates report name/description to “Governance, Policy & Risk” and capability link targets.
src/power-bi/kql/DataIngestion.Report/report.json	Updates capability link targets (finops.org).
src/power-bi/kql/CostSummary.Report/report.json	Updates capability link targets (finops.org).
docs/power-bi.md	Updates visible report tile label to “Usage optimization”.
docs/guide.md	Updates “Explore the framework” link to finops.org.
docs/brand.md	Adds brand/naming/voice guidance for contributors.
docs-mslearn/toolkit/workbooks/optimization.md	Updates naming references to “Usage optimization”.
docs-mslearn/toolkit/workbooks/governance.md	Updates naming references to “Governance, Policy & Risk”.
docs-mslearn/toolkit/workbooks/finops-workbooks-overview.md	Updates capability references to new naming.
docs-mslearn/toolkit/power-bi/workload-optimization.md	Renames “Workload optimization” doc content to “Usage optimization”.
docs-mslearn/toolkit/power-bi/reports.md	Updates report list naming to “Usage optimization” and “Governance, Policy & Risk”.
docs-mslearn/toolkit/optimization-engine/troubleshooting.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/toolkit/optimization-engine/suppress-recommendations.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/toolkit/optimization-engine/setup-options.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/toolkit/optimization-engine/reports.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/toolkit/optimization-engine/overview.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/toolkit/hubs/finops-hubs-overview.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/toolkit/hubs/deploy.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/toolkit/help/errors.md	Updates report name references to “Usage optimization”.
docs-mslearn/toolkit/help/data-dictionary.md	Updates related capability naming to new naming set.
docs-mslearn/toolkit/alerts/finops-alerts-overview.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/toolkit/alerts/configure-finops-alerts.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/index.yml	Updates nav item text for “Usage optimization” and “Governance, Policy & Risk”.
docs-mslearn/framework/understand/allocation.md	Updates internal wording to new governance naming.
docs-mslearn/framework/quantify/planning.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/framework/quantify/benchmarking.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/framework/optimize/workloads.md	Renames capability page to “Usage optimization” and updates related links.
docs-mslearn/framework/optimize/sustainability.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/framework/optimize/rates.md	Updates related capability naming to “Governance, Policy & Risk”.
docs-mslearn/framework/optimize/optimize-cloud-usage-cost.md	Updates section naming to “Usage optimization” and related link text.
docs-mslearn/framework/optimize/licensing.md	Updates related capability naming to “Governance, Policy & Risk”.
docs-mslearn/framework/optimize/architecting.md	Updates related capability naming to “Usage optimization”.
docs-mslearn/framework/manage/onboarding.md	Updates feedback link and related capability naming.
docs-mslearn/framework/manage/manage-finops.md	Updates governance section naming and feedback link.
docs-mslearn/framework/manage/governance.md	Renames capability page to “Governance, Policy & Risk” and updates foundation link.
docs-mslearn/framework/finops-framework.md	Updates framework capability lists to new naming.
docs-mslearn/framework/capabilities.md	Updates framework domain/capability headings to new naming.
docs-mslearn/conduct-iteration.md	Updates capability naming in iteration guidance list.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

RolandKrummenacher

Review

Near-entirely cosmetic terminology/branding pass — three renames (Workload optimization → Usage optimization; Policy and governance → Governance, Policy & Risk; Understand usage and cost → Understand Usage & Cost) applied across MS Learn docs, both Power BI report variants (kql/ + storage/), the ADX dashboard, the optimization workbook, and Build-PowerBI.ps1. Execution is mechanically clean and well-synchronized — the report-pair textboxes, build-script Intro strings, and on-canvas labels were all kept in lockstep, plus some welcome incidental fixes (uage→Usage, shutdown→shut down, This reports uses→This report uses).

Two things worth resolving before merge, then some nice-to-folds.

1. Capitalization is internally inconsistent — and contradicts the brand guide this PR adds

The renames mix two conventions: title-case-with-ampersand (Understand Usage & Cost, Governance, Policy & Risk) alongside sentence case (Usage optimization, Rate optimization, Optimize usage and cost). Meanwhile docs/brand.md — added in this same PR — mandates "sentence case … Reserve title case for proper nouns" and even cites "Rate Optimization" as the official capability name. So the PR ships a guide requiring sentence case while introducing two title-case & headings, and leaves sibling capabilities in sentence case against the guide's own example.

Please pick one convention and apply it uniformly:

If these are official FinOps Foundation proper-noun capability names (the finops.org/.../usage-optimization/, /governance-policy-risk/ slugs suggest the 2025 naming) → all capabilities should be title case (Usage Optimization, Rate Optimization, Data Ingestion…), and the brand.md rule reconciled.
If following the Microsoft Style Guide → "Understand usage and cost" / "Governance, policy, and risk" (no ampersand), matching the other domains.

Right now it's neither, consistently.

2. Framework links repointed off Microsoft Learn → finops.org

docs/guide.md, dashboard.json, and every PBI report description now link the framework capability text to www.finops.org/... instead of learn.microsoft.com/cloud-computing/finops/framework/....

Confirm this is intended (it routes users from MS-owned Learn content to the external Foundation site).
Verify each new slug resolves (usage-optimization, governance-policy-risk, reporting-analytics, invoicing-chargeback, data-ingestion, rate-optimization, domains/*) — a 404 baked into a report description is hard to hotfix.

3. Pre-existing copy bug in a touched section

docs-mslearn/framework/optimize/optimize-cloud-usage-cost.md: under the renamed ## Usage optimization heading, the definition still opens "Onboarding workloads refers to the process of bringing new and existing applications into the cloud…" — wrong capability's text. Cheap to fold in while the section is being edited.

4. Invoicing report — first link segment points to the wrong capability

In both Invoicing.Report/report.json files, the "Invoicing and chargeback " run links to .../reporting-analytics/ while "capability" links to .../invoicing-chargeback/. First segment should also be invoicing-chargeback. (The analogous CostSummary split was effectively corrected.)

5. Minor (no build impact)

Build-PowerBI.ps1 RateOptimization Intro says "insights into rate optimization opportunities" while the report.json textboxes say "insights into any rate optimization opportunities" — different surfaces (PBIX file description vs. on-canvas textbox), so cosmetic only.

Notes

architecture.png is a binary change — couldn't review visually; worth confirming rendered labels match the new naming.
No tests warranted, but CI link validation almost certainly runs — given the volume of URL changes (#2), confirm those gates pass.
Internal .md links correctly left pointing at unchanged filenames (workloads.md, governance.md) — no cross-reference breakage.

Verdict: Clean, well-synchronized rename. Items 1 and 2 are user-facing and worth a deliberate decision before merge; 3–5 are nice-to-folds while the lines are open.

- Remove broken yaml-to-deck GitHub links (lines 82, 166) - Removed PowerPoint template reference (non-existent path) - Removed lint.py reference (non-existent path) - Kept Power BI theme reference (actual file exists) - Update ms.date to 06/17/2026 in 31 docs-mslearn files (was 06/05/2026, stale by 12 days) - Genericize brand.md: replace SRE Agent examples with product-neutral patterns - Line 113: Changed 'FinOps toolkit SRE Agent' to generic placeholder - Line 135: Replaced SRE-specific examples with <Product> placeholders - Line 159: Changed anaphora example from 'Azure SRE Agent' to generic 'Azure Data Explorer' - Line 184-192: Replaced all SRE Agent examples in page title table with Azure Data Explorer - Line 200-204: Updated anaphora short form table (removed SRE Agent, added Power BI) - Line 206: Generic 'product vs component' instead of 'agent vs subagent' - Line 210: Replaced SRE Agent in pattern list with generic products - Line 216: Changed 'subagents' to 'agents' (generic term) - Line 124: Changed URL example from SRE Agent to Azure Data Explorer - Line 240: Generic placeholder in external contributor guidance Brand guidance now provides product-neutral patterns reusable across all FinOps toolkit integrations, not coupled to SRE Agent work (PR #2168). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ocs-powerbi # Conflicts: # docs-mslearn/toolkit/changelog.md # docs-mslearn/toolkit/help/errors.md # docs-mslearn/toolkit/hubs/deploy.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Correct optimize section copy, fix Invoicing report link segment in KQL and storage report.json, refine Build-PowerBI wording, fix Cost Management casing, and set ms.date to today for changed docs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Remove unauthorized docs/brand.md - Revert framework links from finops.org back to Microsoft Learn (guide.md, dashboard.json, 12 Power BI reports) - Normalize capability labels to sentence case per coding guidelines: "Governance, policy, and risk" and "Understand usage and cost" - Fix pre-existing grammar in manage-finops.md ("involve refers to" -> "refers to") - Refresh ms.date on modified docs-mslearn pages Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

MSBrett · 2026-06-21T16:31:34Z

Thanks @RolandKrummenacher — all addressed in 524777e:

Capitalization — Normalized to sentence case per docs-wiki/Coding-guidelines.md (sentence case unless a product name): "Governance, Policy & Risk" → Governance, policy, and risk, and "Understand Usage & Cost" → Understand usage and cost. The unauthorized docs/brand.md that introduced the contradiction was removed, so the only governing rule is the coding guideline.
Framework links — Reverted the Learn → finops.org repoint back to learn.microsoft.com/.../framework/... across docs/guide.md, dashboard.json (4 domain cards), and all 12 Power BI reports. Existing "FinOps Foundation documentation" cross-references in the framework capability pages were intentionally left as-is.
optimize-cloud-usage-cost.md — The "Usage optimization" section now describes usage optimization (no longer the onboarding-workloads text).
Invoicing report — Both link runs now resolve to the same capability (invoicing-chargeback on Learn after the revert).
Build-PowerBI.ps1 vs report.json — Both surfaces now read "insights into any rate optimization opportunities".

Notes:

architecture.png — Confirmed: the diagram contains no renamed capability/domain labels (it shows Azure services and data-flow steps), so there's nothing to reconcile with the naming changes.
Also folded in a pre-existing grammar fix in manage-finops.md ("involve refers to" → "refers to") and refreshed ms.date on the modified pages.

…ocs-powerbi # Conflicts: # docs-mslearn/toolkit/changelog.md

Set ms.date to today on all docs-mslearn pages changed in this PR so the update-mslearn-dates CI check passes on the protected branch (the bot cannot push to update them automatically). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

flanakin · 2026-06-22T06:37:10Z

The direction of the query arrows from dashboards/reports to data got reversed. Those should flip back.

msbrett added 2 commits June 3, 2026 07:48

docs: update FinOps guidance and report labels

9f3a273

fix(docs): remove markdown trailing whitespace

cbc9a3a

MSBrett mentioned this pull request Jun 3, 2026

Azure SRE Agent template, tools, schedules, and docs #2111

Closed

microsoft-github-policy-service Bot added the Needs: Review 👀 PR that is ready to be reviewed label Jun 3, 2026

MSBrett marked this pull request as ready for review June 3, 2026 15:54

Copilot AI review requested due to automatic review settings June 3, 2026 15:54

MSBrett requested review from RolandKrummenacher, arthurclares, flanakin, helderpinto and nteyan as code owners June 3, 2026 15:54

Copilot started reviewing on behalf of MSBrett June 3, 2026 15:54 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

msbrett and others added 3 commits June 3, 2026 09:39

fix(docs): address review comments and ms.date

bd0dffe

fix(docs): update remaining ms.date

66c152d

fix(docs): refresh Learn doc dates

a224c22

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

MSBrett enabled auto-merge (squash) June 4, 2026 13:19

msbrett and others added 2 commits June 5, 2026 01:51

docs: add changelog for naming updates

1fb9304

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

fix(docs): refresh Learn changelog dates

fdf09fa

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

RolandKrummenacher reviewed Jun 17, 2026

View reviewed changes

msbrett and others added 5 commits June 17, 2026 11:27

Merge remote-tracking branch 'origin/dev' into features/sre-general-d…

6dd3d59

…ocs-powerbi # Conflicts: # docs-mslearn/toolkit/changelog.md # docs-mslearn/toolkit/help/errors.md # docs-mslearn/toolkit/hubs/deploy.md

fix(docs): resolve ms.date merge markers (keep today's date)

bef51fd

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

MSBrett changed the title ~~docs: update FinOps guidance and report labels~~ docs: align toolkit terminology with current FinOps Framework naming Jun 21, 2026

MSBrett and others added 2 commits June 21, 2026 09:38

Merge remote-tracking branch 'origin/dev' into features/sre-general-d…

73f0542

…ocs-powerbi # Conflicts: # docs-mslearn/toolkit/changelog.md

flanakin approved these changes Jun 22, 2026

View reviewed changes

flanakin added this to the v15 milestone Jun 24, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: align toolkit terminology with current FinOps Framework naming#2170

docs: align toolkit terminology with current FinOps Framework naming#2170
MSBrett wants to merge 14 commits into
devfrom
features/sre-general-docs-powerbi

MSBrett commented Jun 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

RolandKrummenacher left a comment

Uh oh!

MSBrett commented Jun 21, 2026

Uh oh!

flanakin Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

MSBrett commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

Why it's large

What changed

Risk

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

RolandKrummenacher left a comment

Choose a reason for hiding this comment

Review

1. Capitalization is internally inconsistent — and contradicts the brand guide this PR adds

2. Framework links repointed off Microsoft Learn → finops.org

3. Pre-existing copy bug in a touched section

4. Invoicing report — first link segment points to the wrong capability

5. Minor (no build impact)

Notes

Uh oh!

MSBrett commented Jun 21, 2026

Uh oh!

flanakin Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MSBrett commented Jun 3, 2026 •

edited

Loading