How to Measure Documentation Page Speed Without Fooling Yourself

A Lighthouse score is not the same thing as page speed.

It is a weighted summary of several lab measurements taken under one set of simulated conditions. It can move because the page changed, but it can also move because the test machine, network route, cache state, browser version, or content changed.

That distinction matters when documentation is part of your product. Developers open docs while evaluating an API, debugging an integration, or trying to complete a task. A slow page adds friction at exactly the moment they need an answer. A misleading benchmark is not much better, because it sends the team toward fixes that may not improve the experience at all.

This guide explains what the major performance metrics mean, how to run a repeatable documentation performance test, and how we used that process to improve a live customer documentation site without confusing one synthetic score for a universal result.

The short version

If you only remember five rules, use these:

1. Measure the same URL, content, device profile, region, Lighthouse version, and cache state before and after a change.
2. Run several tests and report the median and range, not the best screenshot.
3. Identify the actual Largest Contentful Paint element and its request waterfall before trying to improve LCP.
4. Keep lab data and real-user field data separate. They answer different questions.
5. Require causal evidence. If you claim an image change improved LCP, show lower image bytes, a shorter resource duration, and a better LCP across repeat runs.

What the Lighthouse performance score actually measures

Lighthouse calculates its performance score by converting raw measurements into individual metric scores, then combining them with these weights:

The raw values do not map linearly to the final score. Lighthouse uses scoring curves based on real web-performance data. Moving from 60 to 90 does not mean the page became 50 percent faster, and moving from 99 to 100 can require more work than moving from 90 to 94.

Opportunities and diagnostics do not award points directly. They are hypotheses. The score only changes when the measured metrics change.

This is why a report should start with the underlying metrics, not the large number in the circle.

What each metric tells you

First Contentful Paint

First Contentful Paint measures when the first eligible content appears. A navigation bar can satisfy FCP even if the article remains blank, so it is useful but incomplete.

For documentation, compare FCP with LCP and the filmstrip. If the shell appears quickly but the actual guide arrives several seconds later, the page still feels slow.

Largest Contentful Paint

Largest Contentful Paint is often the most useful loading metric for a documentation page because the largest element is frequently the page heading, introductory text, or hero image.

Break image LCP into four parts:

1document response
2  -> resource load delay
3  -> resource download duration
4  -> element render delay
5  -> LCP

Do not assume a smaller image will fix LCP. If JavaScript, CSS, fonts, or client rendering prevent the browser from painting the element, download size may not be the dominant delay.

Total Blocking Time

Total Blocking Time adds the portions of main-thread tasks that exceed 50 milliseconds during Lighthouse's measurement window.

For example, tasks lasting 120, 80, and 30 milliseconds contribute 70 + 30 + 0 = 100 milliseconds of TBT.

TBT is a lab diagnostic for load-time responsiveness. It is not the same as field Interaction to Next Paint, and backend processing time is not automatically browser blocking time.

Cumulative Layout Shift

Cumulative Layout Shift measures unexpected visual movement. It is a unitless score, not a duration.

Documentation sites commonly introduce shifts through images without reserved space, late-loading fonts, dynamic banners, search widgets, and navigation that changes size after hydration. A navigation-only audit can miss a shift that happens later while someone reads or opens an interactive example.

Speed Index

Speed Index estimates how quickly visible content fills in across loading frames. A page that stays mostly blank for longer will score worse even if both pages finish loading at the same time.

Use the filmstrip with this metric. It often explains the difference between a page that technically rendered and a page that felt ready.

Lab data and field data are different products

PageSpeed Insights shows two kinds of evidence:

• Lab data comes from Lighthouse under simulated conditions. It is useful for debugging because you can reproduce a test and inspect a trace.
• Field data comes from the Chrome User Experience Report when enough real-user samples exist. It reflects the previous 28 days and shows how actual visitors experienced the page or origin.

The current Core Web Vitals are LCP, Interaction to Next Paint, and CLS. Google's recommended good thresholds are:

These thresholds should be evaluated at the 75th percentile and segmented by mobile and desktop. A page passes when all available Core Web Vitals meet the good threshold.

No field data does not mean the page passed. It usually means the URL or origin did not have enough eligible Chrome traffic. For smaller documentation sites, add real-user monitoring rather than treating an empty CrUX panel as a green result.

Why documentation performance needs its own test plan

A documentation site is not one page type. A useful test set should include:

• a homepage or index page
• a normal prose guide
• a long or image-heavy guide
• an API reference page
• a page with search, AI, or an interactive playground

The slowest path may differ. A prose page can suffer from fonts and render-blocking CSS while an API reference can suffer from a large serialized schema, client hydration, or syntax-highlighting JavaScript.

Caching adds another layer. A typical hosted documentation request may look like this:

1request
2  -> edge or ISR cache lookup
3  -> backend props API on a miss
4  -> database and storage reads
5  -> HTML generation
6  -> browser assets and JavaScript
7  -> paint

A warm cached response can avoid most server work. A cold generation test exercises a different path. Label cache state explicitly instead of averaging both into one number.

A repeatable documentation performance protocol

1. Fix the test inputs

Keep the URL, published content, Lighthouse version, browser version, viewport, throttling profile, region, analytics configuration, and revision constant. Record all of them with the result.

Do not compare a development server with a production build. Do not compare one page after a large content import with a smaller page from the week before.

2. Validate the page before accepting a run

Confirm that the test loaded the correct tenant and article. Check that images, navigation, API examples, and required data appeared. Reject error pages, missing-content responses, and runs with browser failures.

Save the screenshot or filmstrip. A performance score from the wrong page is still wrong.

3. Separate server and browser timing

Measure database time, storage checks, complete API latency, HTML generation, time to first byte, asset loading, script evaluation, and paint independently.

Do not add overlapping spans or call a database microbenchmark an LCP improvement. Faster server work can improve a cold response while leaving a warm cached page unchanged.

4. Run repeated samples

Run at least five sequential mobile tests per controlled condition on a quiet machine. Save the individual results, median, range, Lighthouse report, trace, and screenshot.

Five lab runs are enough to expose obvious variability. They are not enough to claim a production p95.

5. Change one hypothesis at a time

Examples include:

• resize an LCP image
• discover the LCP resource earlier
• remove unused page data
• defer an optional analytics SDK
• reduce initial JavaScript
• reserve space for images and widgets
• improve cache reuse

Rebuild and repeat the same test. If the before and after ranges overlap heavily, call the result inconclusive and investigate further.

6. Keep functionality in the test

A fast documentation page that breaks search, removes analytics, hides API examples, or delays the first interaction without feedback is not an improvement.

Verify content, navigation, custom-domain routing, publish freshness, search, AI, and playground interactions after the performance pass.

What changed when we optimized a live documentation site

In September 2026, we applied this process to Backboard's DocsAlot-hosted documentation.

The initial mobile PageSpeed run scored 77 with a 2.4 second FCP and 5.2 second LCP. Later repeat runs after the optimization work scored between 88 and 96, with a 1.7 second FCP and LCP results between 2.6 and 3.8 seconds.

The range matters. We did not describe the site as having a guaranteed score of 96. The repeat runs showed both a meaningful improvement and normal lab variability.

The useful evidence was underneath the score:

• the shared stylesheet was inlined, removing a blocking CSS request
• the primary Latin font fell from about 130 KB to about 31.5 KB
• analytics SDK imports moved out of the critical loading path
• unused OpenAPI specifications were removed from normal prose-page props
• the prose HTML response fell from 350,713 to 202,921 bytes
• the compressed response fell from 53,058 to 34,735 bytes
• content, navigation, search, API pages, and the playground were rechecked after release

Those measurements explain why the page changed. The Lighthouse score summarizes the result, but it is not the causal evidence.

You can inspect the recorded baseline and two later mobile runs, run one and run two. They are dated lab reports for one page, not a guarantee for every DocsAlot site or every future run.

Common performance claims to avoid

"The score improved by 50 percent"

Lighthouse scores are nonlinear. Report the score change in points, then report the time or stability metrics separately.

"We reduced database time by 80 percent, so LCP improved by 80 percent"

Database time is one part of one server path. A warm cached request may not touch the database, and the browser may still spend most of its time waiting on fonts, CSS, images, or JavaScript.

"One run proves this platform is faster"

One run compares two URLs under one set of conditions. Different content, regions, cache states, and test versions can overwhelm the platform difference. Use repeated, controlled tests and narrow the claim to what was measured.

"No CrUX data means the site is fast"

It means the dataset does not contain enough eligible traffic to report. Add real-user monitoring if the field panel is empty.

"A score of 100 means every user gets a fast page"

A perfect lab score is difficult and useful as a regression signal, but it does not replace field LCP, INP, and CLS across real devices and regions.

The performance report your team should keep

For each accepted run, record:

• timestamp and revision
• URL, page type, and content version
• browser, Lighthouse, and Node versions
• viewport, network, CPU, and region
• browser, edge, and server cache state
• performance score, FCP, LCP, TBT, CLS, and Speed Index
• LCP element and timing breakdown
• time to first byte and relevant API timing
• HTML, image, JavaScript, font, and serialized-data bytes
• errors, screenshots, traces, and report paths

Report time reduction as (before - after) / before x 100. Report a Lighthouse score change in points. Never assemble a synthetic result by mixing the best metrics from different runs.

Measure the experience, not the badge

The goal is not a green circle. The goal is documentation that appears quickly, stays stable, responds when a developer interacts with it, and remains correct after every optimization.

Lighthouse is valuable because it makes the loading path observable. It becomes misleading when the score replaces the investigation.

If you are evaluating documentation infrastructure, compare the same content under the same conditions, inspect the actual bottleneck, and preserve the raw reports. That process is slower than taking one screenshot, but it produces decisions you can trust.

For the other half of documentation delivery, read how to make your documentation AI-readable.