Improve metadata quality lints and doc accuracy

lordhumunguz · lordhumunguz · commit 686c7664ceb8 · 2026-01-17T17:48:37.000-05:00
diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml
@@ -81,6 +81,14 @@ jobs:
       - name: Validate Page Metadata and Orphans
         run: python3 scripts/docs_inventory.py
 
+      # Placeholder language guardrail
+      - name: Reject Placeholder Language
+        run: python3 scripts/docs_placeholder_lint.py
+
+      # dbt-backed column accuracy (via schema docs yaml blocks)
+      - name: Validate Column References
+        run: python3 scripts/docs_column_accuracy.py
+
       # Navigation reference validation
       - name: Validate Navigation References
         run: |
diff --git a/data-activation/managed-data-warehouse/bi-tools.mdx b/data-activation/managed-data-warehouse/bi-tools.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Connecting BI Tools'
-description: 'Learn about Connecting BI Tools in SourceMedium.'
+description: 'Supported BI tools and templates for connecting to a SourceMedium Managed Data Warehouse.'
 icon: "chart-line"
 ---
 ## Overview
diff --git a/data-activation/managed-data-warehouse/overview.mdx b/data-activation/managed-data-warehouse/overview.mdx
@@ -1,11 +1,11 @@
 ---
 title: 'Overview'
-description: 'Learn about Overview in SourceMedium.'
+description: "What SourceMedium’s Managed Data Warehouse is and how to activate it via BI templates or custom modeling."
 icon: "chart-line"
 ---
 ## What Is A Managed Data Warehouse?
 
-SourceMedium's Managed Data Warehouse offering helps simplify data warehouse adoption, a tablestakes 
+SourceMedium's Managed Data Warehouse offering helps simplify data warehouse adoption, a table-stakes
 technology investment for businesses looking to establish a competitive advantage through data and advanced analytics.
 
 Once we've ingested data from the sources you've integrated, we run our [transformation pipeline](/data-transformations/philosophy) and deliver data into a 
diff --git a/data-activation/template-resources/sm-looker-report-template-directory.mdx b/data-activation/template-resources/sm-looker-report-template-directory.mdx
@@ -1,7 +1,7 @@
 ---
 title: 'Looker Studio - Report Template Directory'
 sidebarTitle: 'Report Template Directory'
-description: 'Learn about Looker Studio - Report Template Directory in SourceMedium.'
+description: 'Directory of SourceMedium Looker Studio report templates and the data sources required for each.'
 icon: "book"
 ---
 ## Overview
diff --git a/data-activation/template-resources/sm-sql-recipe-directory.mdx b/data-activation/template-resources/sm-sql-recipe-directory.mdx
@@ -61,4 +61,4 @@ Notes:
 
 ## More recipes
 
-More recipes are coming soon. If there’s a query you’d like added (subscription churn, cohort LTV curves, creative performance, etc.), reach out to your SourceMedium team and include the business question and the table(s) you’re using.
+We regularly add new recipes. If there’s a query you’d like added (subscription churn, cohort LTV curves, creative performance, etc.), reach out to your SourceMedium team and include the business question and the table(s) you’re using.
diff --git a/data-inputs/configuration-sheet/can-i-set-targets-in-my-dashboard.mdx b/data-inputs/configuration-sheet/can-i-set-targets-in-my-dashboard.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Can I set targets in my dashboard?"
-description: "Learn about Can I set targets in my dashboard? in SourceMedium."
+description: "How to configure metric targets in the configuration sheet and surface target widgets in Executive Summary."
 sidebarTitle: "Setting Metric Targets"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/costs/how-do-i-add-historic-product-costs-from-shopify-into-my-dashboard.mdx b/data-inputs/configuration-sheet/costs/how-do-i-add-historic-product-costs-from-shopify-into-my-dashboard.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How do I add historic Product Costs from Shopify into my dashboard"
-description: "Learn about How do I add historic Product Costs from Shopify into my dashboard in SourceMedium."
+description: "How to backfill historic Shopify product costs (COGS) so gross profit and LTV metrics reflect accurate margins."
 sidebarTitle: "Adding Historic Product Costs"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/costs/how-do-i-override-product-costs-from-shopify-into-my-dashboard.mdx b/data-inputs/configuration-sheet/costs/how-do-i-override-product-costs-from-shopify-into-my-dashboard.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How do I override Product Costs from Shopify into my dashboard?"
-description: "Learn about How do I override Product Costs from Shopify into my dashboard? in SourceMedium."
+description: "How to override Shopify product costs (COGS) via the configuration sheet so reporting uses your preferred cost basis."
 sidebarTitle: "Overriding Product Costs"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/costs/how-do-i-surface-fulfillment-costs-within-my-dashboard.mdx b/data-inputs/configuration-sheet/costs/how-do-i-surface-fulfillment-costs-within-my-dashboard.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How do I surface Fulfillment Costs within my dashboard?"
-description: "Learn about How do I surface Fulfillment Costs within my dashboard? in SourceMedium."
+description: "How to add fulfillment/3PL costs via the configuration sheet so they’re included in gross profit reporting."
 sidebarTitle: "Surfacing Fullfillment Costs"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/costs/how-do-i-surface-merchant-processing-fees-within-my-dashboard.mdx b/data-inputs/configuration-sheet/costs/how-do-i-surface-merchant-processing-fees-within-my-dashboard.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How do I surface Merchant Processing Fees within my dashboard?"
-description: "Learn about How do I surface Merchant Processing Fees within my dashboard? in SourceMedium."
+description: "How to add merchant processing fees via the configuration sheet so they’re allocated into profit and order reporting."
 sidebarTitle: "Surfacing Merchant Processing Fees"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/costs/how-do-i-surface-operating-expenses-within-my-dashboard.mdx b/data-inputs/configuration-sheet/costs/how-do-i-surface-operating-expenses-within-my-dashboard.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How do I surface Operating Expenses within my dashboard?"
-description: "Learn about How do I surface Operating Expenses within my dashboard? in SourceMedium."
+description: "How to add operating expenses in the configuration sheet so they appear in executive reporting."
 sidebarTitle: "Surfacing Operating Expenses"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/costs/how-do-i-surface-product-costs-from-platforms-outside-of-shopify-into-my-dashboard.mdx b/data-inputs/configuration-sheet/costs/how-do-i-surface-product-costs-from-platforms-outside-of-shopify-into-my-dashboard.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How do I surface Product Costs from Platforms outside of Shopify into my dashboard?"
-description: "Learn about How do I surface Product Costs from Platforms outside of Shopify into my dashboard? in SourceMedium."
+description: "How to add non-Shopify product costs (COGS) for channels like Amazon/Retail/Wholesale via the configuration sheet."
 sidebarTitle: "Surfacing Non-Shopify Product Costs"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/costs/how-do-i-surface-product-costs.mdx b/data-inputs/configuration-sheet/costs/how-do-i-surface-product-costs.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How do I surface Product Costs/COGS within my dashboard?"
-description: "Learn about How do I surface Product Costs/COGS within my dashboard? in SourceMedium."
+description: "How to surface Shopify product costs (COGS) so product gross profit and related metrics are available in dashboards."
 sidebarTitle: "How to surface Shopify Product Costs"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/costs/how-do-i-surface-shipping-costs-within-my-dashboard.mdx b/data-inputs/configuration-sheet/costs/how-do-i-surface-shipping-costs-within-my-dashboard.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How do I surface Shipping Costs within my dashboard?"
-description: "Learn about How do I surface Shipping Costs within my dashboard? in SourceMedium."
+description: "How to add shipping costs via the configuration sheet so they’re reflected in executive and LTV/profit metrics."
 sidebarTitle: "Surfacing Shipping Costs"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/how-can-i-create-order-channels-and-subchannels.mdx b/data-inputs/configuration-sheet/how-can-i-create-order-channels-and-subchannels.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How can I create order channels and sub-channels?"
-description: "Learn about How can I create order channels and sub-channels? in SourceMedium."
+description: "How to create channel mapping rules in the configuration sheet to group orders into channels and sub-channels."
 sidebarTitle: "Creating order Channels & Sub-Channels"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/how-can-i-track-influencer-spend-and-performance.mdx b/data-inputs/configuration-sheet/how-can-i-track-influencer-spend-and-performance.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How can I track influencer spend and performance?"
-description: "Learn about How can I track influencer spend and performance? in SourceMedium."
+description: "How to track influencer spend and performance using discount codes and the configuration sheet Cost tab."
 sidebarTitle: "Tracking Influencer Spend & Performance"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/how-do-i-enter-non-integrated-sales-data-sales-tab.mdx b/data-inputs/configuration-sheet/how-do-i-enter-non-integrated-sales-data-sales-tab.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How do I enter non-integrated sales data through my Configuration Sheet (Sales tab)?"
-description: "Learn about How do I enter non-integrated sales data through my Configuration Sheet (Sales tab)? in SourceMedium."
+description: "How to add sales from non-integrated platforms (retail/wholesale/etc.) using the configuration sheet Sales tab."
 sidebarTitle: "Entering non-intergrated sales data"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/how-do-i-include-marketing-spend-through-the-cost-tab-of-the-configuration-sheet.mdx b/data-inputs/configuration-sheet/how-do-i-include-marketing-spend-through-the-cost-tab-of-the-configuration-sheet.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How do I include marketing spend through the cost tab of the configuration sheet?"
-description: "Learn about How do I include marketing spend through the cost tab of the configuration sheet? in SourceMedium."
+description: "How to add non-integrated marketing spend via the configuration sheet Cost tab so it appears in executive and marketing reporting."
 sidebarTitle: "Adding Marketing Spend Using the Cost Tab"
 icon: 'question-mark'
 ---
diff --git a/data-inputs/configuration-sheet/how_does_channel_mapping_work.mdx b/data-inputs/configuration-sheet/how_does_channel_mapping_work.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How does channel mapping work in the SourceMedium Dashboard?"
-description: "Learn about How does channel mapping work in the SourceMedium Dashboard? in SourceMedium."
+description: "How SourceMedium assigns orders and spend to channels, including the precedence rules and default logic."
 sidebarTitle: "How does channel mapping work?"
 icon: 'question-mark'
 ---
diff --git a/data-transformations/naming-conventions/boolean-columns.mdx b/data-transformations/naming-conventions/boolean-columns.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Boolean Columns'
-description: 'Learn about Boolean Columns in SourceMedium.'
+description: 'Naming rules for boolean fields (`is_...`) so true/false columns read like a question.'
 icon: "tags"
 ---
 ### Overview
diff --git a/data-transformations/naming-conventions/dimension-columns.mdx b/data-transformations/naming-conventions/dimension-columns.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Dimension Columns'
-description: 'Learn about Dimension Columns in SourceMedium.'
+description: 'How we name dimension columns (attributes) for consistent filtering and grouping.'
 icon: "tags"
 ---
 ### Overview
diff --git a/data-transformations/naming-conventions/key-concepts.mdx b/data-transformations/naming-conventions/key-concepts.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Key Concepts'
-description: 'Learn about Key Concepts in SourceMedium.'
+description: 'Definitions of the building blocks we use in naming conventions (entity, metric, dimension, modifier, prefix, suffix).'
 icon: "tags"
 ---
 ### Overview
diff --git a/data-transformations/naming-conventions/metric-columns.mdx b/data-transformations/naming-conventions/metric-columns.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Metric Columns'
-description: 'Learn about Metric Columns in SourceMedium.'
+description: 'How we name metric columns so they’re readable and consistent across the warehouse.'
 icon: "tags"
 ---
 ### Overview
diff --git a/data-transformations/naming-conventions/numerical-columns.mdx b/data-transformations/naming-conventions/numerical-columns.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Numerical Columns'
-description: 'Learn about Numerical Columns in SourceMedium.'
+description: 'Naming patterns for numeric metrics where aggregation/meaning is implied by convention.'
 icon: "tags"
 ---
 ### Overview
diff --git a/data-transformations/naming-conventions/sourcemedium-proprietary-columns.mdx b/data-transformations/naming-conventions/sourcemedium-proprietary-columns.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Proprietary Columns'
-description: 'Learn about Proprietary Columns in SourceMedium.'
+description: 'How to recognize SourceMedium-derived columns (the `sm_` prefix) and what they represent.'
 icon: "tags"
 ---
 ### Overview
diff --git a/data-transformations/naming-conventions/table-names.mdx b/data-transformations/naming-conventions/table-names.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Table Names'
-description: 'Learn about Table Names in SourceMedium.'
+description: 'How we name tables (`fct_`, `dim_`, `obt_`, `rpt_`) so datasets are easy to navigate.'
 icon: "tags"
 ---
 ### Table Structure Overview
diff --git a/data-transformations/naming-conventions/time-columns.mdx b/data-transformations/naming-conventions/time-columns.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Time Columns'
-description: 'Learn about Time Columns in SourceMedium.'
+description: 'How we name timestamps and datetimes (including localized time) across SourceMedium tables.'
 icon: "tags"
 ---
 ### Overview
diff --git a/help-center/what-is-sourcemedium.mdx b/help-center/what-is-sourcemedium.mdx
@@ -1,6 +1,6 @@
 ---
 title: "What Is SourceMedium"
-description: "Learn about What Is SourceMedium in SourceMedium."
+description: "Overview of SourceMedium and how to use this Help Center to find onboarding, integrations, configuration tutorials, and support."
 icon: 'map'
 ---
 SourceMedium is a 
@@ -14,7 +14,7 @@ data ingestion and transformation processes that streamline the journey from raw
 To learn more about how we do this, see [Data Transformation](/data-transformations/philosophy) and [Data Activation](/data-activation/managed-data-warehouse/overview).
 
 <Note>
-    **This help center is currently under construction.**
+    We’re actively expanding this Help Center. If you can’t find what you need, contact your SourceMedium team and tell us what you were trying to accomplish.
     
     All information presented is accurate and up to date, but stay tuned for more to come!
 </Note>
diff --git a/mta/mta-dash-provisioning.mdx b/mta/mta-dash-provisioning.mdx
@@ -1,6 +1,6 @@
 ---
 title: "How to Self-Service Provision Your Source Medium MTA Dashboard"
-description: "Learn about How to Self-Service Provision Your Source Medium MTA Dashboard in SourceMedium."
+description: "How to copy the MTA Looker Studio template and connect it to your warehouse data sources."
 sidebarTitle: "MTA Dash Provisioning"
 icon: "chart-bar"
 iconType: "solid"
diff --git a/onboarding/data-docs/tables/customer_details_dda.mdx b/onboarding/data-docs/tables/customer_details_dda.mdx
@@ -35,8 +35,8 @@ The **Customer Details** table (`obt_customers`) provides customer-level data in
 | `customer_email_hashed` | SHA-256 hash of email for privacy-safe matching |
 | `customer_email` | Customer email address (PII) |
 | `customer_created_at` | When the customer record was created |
-| `first_order_id` | ID of customer's first order |
-| `last_order_id` | ID of customer's most recent order |
+| `customer_first_order_id` | ID of customer's first order |
+| `customer_last_order_id` | ID of customer's most recent order |
 | `subscriber_status` | Current subscription status |
 | `customer_tags_csv` | Customer tags from your platform |
 
diff --git a/onboarding/getting-started/level-2-data-checklist.mdx b/onboarding/getting-started/level-2-data-checklist.mdx
@@ -36,7 +36,7 @@ recommended best practices to enhance your data setup and supercharge your insig
 
 Stay tuned for more checklists, and get ready to unlock the power of your data 🔐
 
-- **Level 3** (coming soon!): Deep dive customer, order, and product level analysis
+- **Level 3**: Deep dive customer, order, and product level analysis
 
 ### **Recap**
 
diff --git a/scripts/docs_column_accuracy.py b/scripts/docs_column_accuracy.py
diff --git a/scripts/docs_inventory.py b/scripts/docs_inventory.py
diff --git a/scripts/docs_placeholder_lint.py b/scripts/docs_placeholder_lint.py

Original file line number	Diff line number	Diff line change
`@@ -61,4 +61,4 @@ Notes:`
`61`	`61`
`62`	`62`	`## More recipes`
`63`	`63`
`64`		`-More recipes are coming soon. If there’s a query you’d like added (subscription churn, cohort LTV curves, creative performance, etc.), reach out to your SourceMedium team and include the business question and the table(s) you’re using.`
	`64`	`+We regularly add new recipes. If there’s a query you’d like added (subscription churn, cohort LTV curves, creative performance, etc.), reach out to your SourceMedium team and include the business question and the table(s) you’re using.`