dashboard in a markdown file: the low-tech metrics habit

TL;DR

A markdown file with your key numbers, updated weekly by a script or by hand, beats a dashboard nobody opens. It lives in version control, diffs show you exactly what changed, and writing the commentary forces you to understand the numbers. Start with ten lines: four headline metrics, three movers, and three lines of your own words.

dashboard in a markdown file: the low-tech metrics habit

Use this when

• You built a dashboard once and stopped opening it
• The team is small and BI tooling is overhead
• You want metrics history in version control with diffs
• A founder wants "just send me the numbers" weekly
• Your metrics fit on one screen and always will

Not for this skill when

• You need real-time or near-real-time monitoring (different discipline)
• Many people need sliced, interactive exploration (that is BI tooling)
• Metrics access must be permissioned per viewer (a file is all-or-nothing)
• You are tracking hundreds of metrics across teams

Steps

1. Write the file by hand once, with real numbers. Headlines with week-over-week change, what moved and your best guess why, and what you are watching next week. If it is longer than a screen, cut it; length is where dashboards go to die.

   # Metrics 2026-10-04
   ## Headlines (vs last week)
   - weekly active agents: 312 (+8%)
   - successful queries: 4,102 (+12%)
   ## What moved
   ## Watch next week

Expected output: one complete file. Success check: a teammate understands the week from it in two minutes.

1. Put it in version control next to the code. Dated files in one directory, or one file with dated sections; either way, git history becomes your metrics history and diffs become your change log. This is the feature no dashboard gives you for free.

   metrics/2026-10-04.md, metrics/2026-09-27.md, ...

Expected output: metrics directory in the repo. Success check: git log on the directory tells the story of the last quarter.

1. Automate the number-filling, not the thinking. A script pulls the headline numbers into the template; you still write the "what moved" section by hand every week. Automating the commentary produces confident-sounding nonsense.

   [ ] script fills headlines from data sources
   [ ] human writes movers and watch items weekly

Expected output: a fill script plus a human habit. Success check: the script's numbers match a manual pull three weeks running.

1. Review it on a fixed cadence and keep the cadence. Weekly, same day, same readers. The habit is the dashboard; a perfect file nobody reviews on schedule is a diary.

   review: every [day], readers: [names], timebox: 20 min

Expected output: a calendar event with readers. Success check: three consecutive reviews happened on schedule.

1. Prune metrics that never drive decisions. If a headline has not influenced a decision in two months, demote it to an appendix or delete it. Dashboards accrete metrics; the prune is what keeps this one readable.

   pruned this month: [metrics], reason: [one line each]

Expected output: a shorter file over time. Success check: the headline count stays under ten.

Variant phrasings

Simple KPI tracking without a dashboard tool

Tool-skeptic phrasing. The whole skill: a file, version control, and a cadence beat tooling for small teams.

Metrics in git

Version-control phrasing. Step 2 is the pitch: diffs of your metrics history are a superpower for postmortems.

Weekly metrics file template

Template phrasing. Step 1's structure is the template; copy it and fill it.

How to make founders actually read metrics

Audience phrasing. Short, same format every week, commentary in plain language; step 4's fixed cadence does the rest.

Why it happens

Dashboards fail socially, not technically: they require someone to remember to open them, they show fifty numbers with equal weight, and they never say what changed or why it matters. A markdown file inverts all three: it arrives (via the cadence), it shows ten numbers, and the human-written section says what matters. Version control adds the history that dashboard tools charge extra for.

Edge cases / pitfalls

• Do not commit secrets in the fill script. API keys and credentials live in the environment or a vault, never in the repo beside the metrics.
• Hand-editing numbers "to look better" will happen once under pressure; git history makes it visible, which is the point. Agree as a team that the file is write-once per week.
• If the team grows past the point where everyone fits in one review, graduate to real BI. This habit scales to about ten people, then it becomes a bottleneck.
• Charts are the one thing markdown does poorly. Link out to a chart image or accept sparklines in text; do not contort the format.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstFNZrtTgCIcF1yQ-UNBkjA