Documenting quality so others trust you

You profiled. You deduped. You mapped categories. You labeled time zones. You automated checks. Then a new analyst joined, rebuilt a metric from the wrong table, and the exec channel learned about “your” number the hard way. The work was solid. The trust surface was invisible. Quality that only lives in your head does not scale past vacation coverage.

This is Part 7 of Data quality for people who ship numbers, the last part of the series. Parts 1 through 6 made quality operational. Now you document just enough that others can rely on your datasets without a committee, a 40-page standard, or a tool nobody opens. Think of this as a light scorecard: dataset, owner, metrics, known issues, next check. Program-level governance still matters. We already publish that lens in Data Governance 101 and Master Data Management. This post is the analyst-scale version you can ship this month. Skills from the SQL series, Python for analytics, From spreadsheets to real data, and Analytics foundations all feed the same habit: make the contract readable.

What you’ll learn

• Why light documentation beats both silence and bureaucracy
• A scorecard template with dataset, owner, grain, metrics, issues, and next check
• How to publish trust signals next to the data people actually use
• A worked example scorecard filled from Parts 5 and 6 habits
• How this series fits under broader governance without waiting for a program office

Trust is a product feature, not a personality trait

Example:

The light scorecard (copy this)

Example:

Keep one scorecard per consumer-facing dataset or certified mart, not per raw landing table unless raw is what people query. Prefer the object people argue about in meetings.

That is enough for 90% of workplace trust problems. Resist the urge to invent twenty optional metadata fields before the first five are filled for your top tables.

Quality metrics block (the heart of the card)

Pull metrics from Part 6 checks. Show current value, threshold, and status. Update automatically if you can; update manually on a schedule if you must. Stale green is worse than an honest “unknown.”

When a metric fails, the scorecard should not hide. Put the failure at the top for the day, link the check log, and state the user-facing impact in one sentence: “Do not use customer segment joins until orphans are cleared.”

Where to publish so people actually see it

Documentation dies in orphan wikis. Place the scorecard on the path of consumption:

• BI tool description or certified badge text for the main dashboard
• Warehouse table comment or a sibling view named …_dq that returns the latest status row
• README in the repo that builds the mart, with a rendered Markdown card
• Channel topic or pinned post for the team that gets paged on failure
• Export sidecar for CSV and spreadsheet handoffs (the metadata habit from the Python series)

Pick two surfaces, not seven. Consistency beats coverage. If your company later adopts a catalog, these scorecards become the seed content instead of empty templates.

Known issues: the most underrated trust builder

Hidden caveats destroy credibility. Written caveats build it. A known issue should include:

• What is wrong or limited
• Who is affected
• Since when
• Workaround
• Expected fix or “accepted risk” owner

Examples that read as adult, not weak:

• “Same-day net revenue is incomplete because refunds post up to 48 hours later. Use T+2 for finance-facing nets.”
• “Store 118 migrated POS on 2024-05-01. Pre-migration order IDs can collide with the legacy system; filter source_system.”
• “Category ‘Other’ is still 7% after Part 4 mapping. Do not use for assortment strategy until under 3%.”

This is the same honesty as good-enough data in foundations: confidence language beats fake certainty.

Worked example: Orders daily fact scorecard

Here is a filled card you can adapt. It assumes Part 5 time rules and Part 6 checks exist.

# Data quality scorecard (light)
# Dataset: Orders daily fact
# Technical: analytics.orders_fact
# Version: 2024-06-12

purpose: >
  Certified order-level fact for Sales Ops daily board and the finance
  weekly extract. Not for real-time inventory.

owner:
  primary: Alex Rivera (analytics)
  backup: Sam Chen (analytics)
  channel: #data-sales-ops

grain: one row per order
primary_key: order_id

time_contract:
  event_timestamp: ordered_at_utc (UTC instant)
  business_day: local_business_date (store IANA zone)
  fiscal: join analytics.date_dim on local_business_date
  partial_day_policy: mark current local day as in_progress

consumers:
  - Sales daily dashboard (certified)
  - finance_weekly_orders.csv export job
  - churn features notebook (read-only, secondary)

quality_metrics:
  - name: rows_yesterday
    threshold: ">0 and within 60%-140% of 4-week same-weekday median"
  - name: unique_order_id
    threshold: "0 duplicate keys"
  - name: null_amount_rate
    threshold: "

Example output:

You can store the same content as Markdown, YAML, a warehouse table, or a Notion page. The format is secondary. The fields and the honesty are primary.

Optional: a one-query status face for SQL users

-- Latest scorecard face for BI description or a status tile
SELECT
  dataset_name,
  owner_primary,
  grain,
  overall_status,
  failing_checks,
  known_issues_open,
  last_green_at_utc,
  next_human_review_at
FROM analytics.dq_scorecard_current
WHERE dataset_name = 'orders_fact';

-- overall_status example logic (materialize in your job)
-- FAIL if any gate check failed in the last run
-- WARN if only soft-band checks failed
-- PASS otherwise

Pair this with a tiny Python writer that updates dq_scorecard_current after the Part 6 suite. The scorecard becomes a living object instead of a slide that ages out after the offsite.

from datetime import datetime, timezone

def summarize_suite(results):
    """results: list of objects with .name, .ok, .detail from Part 6."""
    failed = [r for r in results if not r.ok]
    if not failed:
        status = "PASS"
    elif any(r.name.startswith("row_count") or "unique" in r.name for r in failed):
        status = "FAIL"
    else:
        status = "WARN"
    return {
        "dataset_name": "orders_fact",
        "overall_status": status,
        "failing_checks": ", ".join(r.name for r in failed) or None,
        "checked_at_utc": datetime.now(timezone.utc).isoformat(),
        "owner_primary": "Alex Rivera",
    }

# pseudo: write_to_warehouse("analytics.dq_scorecard_current", summarize_suite(results))

Writing for three audiences at once

A scorecard fails if only engineers can parse it. Aim for three readers:

• The rushed stakeholder: purpose, status, known issues, “safe to use for X / not for Y”
• The analyst on call: grain, keys, check names, runbook links, owner
• Future you: why thresholds exist, when exceptions were accepted, what changed last quarter

Lead with plain English. Keep technical names in parentheses. Avoid unexplained acronyms. If you must say SLA, define it once as the promised freshness or quality bar. If you must say RACI, you may already be climbing into program governance, which is fine, but do not force that vocabulary onto a single mart card.

Certification without theater

Some teams stamp dashboards “certified.” The stamp only helps when it means a published scorecard plus green gates. Empty certification is worse than no badge because it teaches leaders to stop asking questions.

A minimal certification contract:

• Named owner and backup
• Grain and primary key written
• Automated suite scheduled with logged results
• Known issues section reviewed in the last 30 days
• Consumer list so you know who to notify on FAIL

If any bullet is missing, call the asset “in progress” or “team use,” not certified. Honesty scales. Theater does not.

How much process is enough?

Use a simple ladder. Climb only when pain demands it.

Most readers of this series should live happily at the light scorecard stage for a long time. That is not a lesser path. It is how quality shows up in the work week. When leadership asks for “governance,” you can point to scorecards and check logs as evidence you already practice stewardship, then grow into program design using the governance articles rather than starting from slogans.

Common mistakes

Rule of thumb: If a competent stranger cannot decide whether to use your table for a board slide after two minutes on the scorecard, the card is not done.

How to practice this week (and close the series)

1. List the five datasets that cause the most Slack arguments. Rank by blast radius, not by elegance.
2. Fill one light scorecard completely, including at least one known issue. If you have zero issues, you are probably not looking.
3. Connect the card to Part 6: paste last run statuses and timestamps.
4. Publish the card on two surfaces (for example BI description + repo README).
5. Walk one stakeholder through the card in ten minutes. Ask what was still ambiguous. Fix those lines.
6. Schedule the Monday human review for 15 minutes. Put it on a calendar like a real meeting.

When those habits stick, you have finished the hands-on quality path: define bad data, profile, dedupe, standardize, fix time, validate, and document trust. For deeper program design, policies, and cross-domain ownership, continue with Data Governance 101 and Master Data Management. For more skill tracks, use the Learn hub.

Series recap: Data quality for people who ship numbers

None of this requires waiting for a perfect platform. It requires repeating small adult habits until the room stops treating data quality as a surprise.

A 30-day rollout plan (one team)

If you want a concrete path from “we should document more” to “we trust our top tables,” try this month-long shape:

1. Week 1: Pick five datasets. Write grain, owner, and purpose only. Share in the team channel for corrections.
2. Week 2: Attach Part 6 checks to the top two datasets. Create the check log table. Fail once on purpose in staging.
3. Week 3: Fill metrics and known issues. Publish scorecards on BI descriptions and READMEs. Walk one stakeholder through each card.
4. Week 4: Add Monday human review. Retire one noisy check. Promote one more dataset from notes to full card. Stop there unless pain demands more.

That plan is deliberately small. Quality programs die when month one tries to boil the ocean. Analysts win when month one makes two dashboards safer and one on-call shift less scary.

Quick recap

• Trust needs a readable contract: purpose, owner, grain, metrics, issues, next check.
• Publish scorecards on the path of use, not only in a distant wiki.
• Known issues written down increase confidence; hidden limits destroy it.
• Automate status from Part 6 checks so green means something measurable.
• Stay light until pain demands catalogs and formal governance programs.

You made it through the series. Ship one scorecard this week. Then go back to the numbers with fewer 5 p.m. mysteries.

Sources

Research and further reading used for this article:

• Wang, R. Y., and Strong, D. M. (1996), Beyond Accuracy: What Data Quality Means to Data Consumers: http://mitiq.mit.edu/Documents/Publications/TDQMpub/14_Beyond_Accuracy.pdf
• DAMA International: https://www.dama.org/
• DAMA NL, Dimensions of Data Quality: https://dama-nl.org/dimensions-of-data-quality-en/
• DATAVERSITY, Data quality dimensions: https://www.dataversity.net/articles/data-quality-dimensions/
• Collibra, The 6 data quality dimensions: https://www.collibra.com/blog/the-6-dimensions-of-data-quality
• IBM, Data quality dimensions: https://www.ibm.com/docs/en/ws-and-kc?topic=quality-data-dimensions
• Analytics Made Simple, Data Governance 101: https://analyticsmadesimple.com/key-terms/data-governance/
• Analytics Made Simple, Master Data Management: https://analyticsmadesimple.com/key-terms/master-data-management/
• Analytics Made Simple, Learn hub: https://analyticsmadesimple.com/learn/
• Analytics Made Simple, Analytics foundations: https://analyticsmadesimple.com/series/analytics-foundations/
• Analytics Made Simple, From spreadsheets to real data: https://analyticsmadesimple.com/series/spreadsheets-to-data/
• Analytics Made Simple, SQL series: https://analyticsmadesimple.com/series/sql/
• Analytics Made Simple, Python for analytics: https://analyticsmadesimple.com/series/python/

Merch on Etsy

Open store →

Dashboard to Excel Ceramic Coffee Mug View on Etsy → Boxplot Mouse Pad, Data Science Mouse Pad, Analytics Mouse Pad, Box Plot, Whisker Plot View on Etsy → You're On Mute White Ceramic Coffee Mug, Data Science Mug, Data Mug, Analytics Mug, Statistics Mug, Programming Mug, Gift Mug, Coffee Mug View on Etsy → You're On Mute White Ceramic Coffee Mug, Data Science Mug, Data Mug, Analytics Mug, Statistics Mug, Programming Mug, Gift Mug, Coffee Mug View on Etsy →