How to Write a Web Performance Improvement Log (with a Template)

Record the baseline with its conditions

The most common gap in a performance log is a “before” number with no conditions. Record the device, the network, the tool, and how many runs. Without those, the after number cannot be compared. Across this site’s web-performance posts, 2 have been collected so far.

State the hypothesis and its evidence

GitHub’s work on site performance moved styling away from a runtime CSS-in-JS layer toward CSS modules. A hypothesis like “runtime styling costs too much” is only useful when you measure what the runtime work costs. Write down which measurement would show the hypothesis is wrong.

Record what you did not change

Regressions often come from a runtime or library upgrade rather than from application code. Note the versions you left alone as well as the ones you changed, because that narrows where the cause can be.

Compare before and after under the same conditions

Use repeated measurements under identical conditions. One run is not evidence of an improvement. If the conditions differ, show the difference as its own column in the table.

Template (copy)

## 1. Target and baseline

- Page, metric (for example, time to first render), measurement setup

## 2. Hypothesis

- What we think is slow, and the evidence for it

## 3. Change

- What changed, and what did not

## 4. Before and after

| Metric | Before | After | Conditions |
|---|---|---|---|

## 5. Rollback criteria and follow-ups

- The metric and threshold that trigger a rollback