The Weekly Report

A measurement programme lives or dies on whether anyone reads its output. One page beats a dashboard with thirty tiles, every time.

The eight numbers

Time to first useful signal — median and ninetieth percentile.

Blocking pipeline duration — same two.

Queue time, separately from execution.

Local incremental build duration, from the local telemetry.

Cache hit rate, local and remote.

Flake rate.

Time to green after a main branch failure.

Onboarding time, refreshed twice a year rather than weekly.

Each names a specific cause when it moves the wrong way, which is the test for whether a measure belongs.

What to leave out

Anything per-developer.

Test counts and lines of code.

Coverage percentage, which belongs in a review context rather than a performance report.

Tool adoption, unless a rollout is in progress.

Number of findings closed, which measures the programme rather than the toolchain.

Averages without percentiles.

The sentence that matters

Every number gets one line of interpretation, written by a person.

What moved, why, and what is being done. Updated when it changes, not restated weekly.

A number without interpretation gets read as noise, and readers supply their own explanation, which is usually wrong.

This is also how you find out whether a measure has an owner. If nobody can write the sentence, nobody is watching it.

Ranges, not targets

Publish the normal range for each measure, from a long baseline.

A point inside it is ordinary, however unwelcome, and should be answered as such.

A point outside it, or a run on one side, or a trend, is investigated and the finding reported.

Do not set targets on these numbers. A target invites optimisation of the measure, and every one of them is gameable.

Segmentation

By repository, which is where the variation is.

By team, carefully, and only to find practices worth copying.

Never by individual.

The aggregate hides the one place where it is bad, which is the argument for segmenting at all.

Where it goes

Into an existing forum — the engineering review, the weekly operations meeting — not a dedicated one.

To the people who can act, which means team leads and whoever owns capacity.

Visible to developers, whose data it is and who will correct it when it is wrong.

Archived, so a question about last quarter has an answer rather than an estimate.

The annual version

What the toolchain looked like a year ago and now, same measures, same definitions.

What was changed and what it moved, including the changes that moved nothing.

What remains unaddressed and why, which is the honest section and the one that justifies the next year's investment.

Establishing the normal range

Without it, every fluctuation generates a question and the report becomes a burden.

Take a long baseline — several weeks covering the usual variation.

Compute the range for each measure.

Mark it on every chart.

State the rule: inside is ordinary, outside is investigated.

Answer questions about ordinary movement with "within the normal range", confidently.

Investigate the exceptions and report what was found, which is what makes the rule credible rather than a way of deflecting.

Keeping it one page

The discipline that determines whether the report is read at all.

Eight numbers is the ceiling, not a target.

Adding a measure means removing one.

Review quarterly: which numbers produced a decision, and which were skimmed.

Remove the ones nobody acts on, which is usually most of what accumulated.

A report that only grows becomes a dashboard, and a dashboard is read once.