Skip to content

Docs: the performance page leads with ranked charts, with a data page and CSVs generated from the benchmark results - #164

Merged
electricessence merged 3 commits into
masterfrom
docs/perf-charts
Nov 16, 2026
Merged

electricessence merged 3 commits into
masterfrom
docs/perf-charts

Conversation

@electricessence

Copy link
Copy Markdown
Collaborator

What this changes

The performance page leads with the results: ranked, colour-coded SVG bar charts, in the order of the interactive ranking page, with the explanation after each chart and a link to its data. Docs only: no Source/, samples or public API change.

Chart first. Every section is a heading, then the chart, then the explanation (one or two sentences on why it is there and what to take from it), then links to its data table and CSV. The page opens with a headline tile row, then: reader-open time, total time per call, memory allocated, cost against the number of columns, the cost of building a map (reused against fresh), the real databases (time and memory), and sync against async reads. The general text (what is measured, the limits) is at the end. All the measured comparisons stay, including the ones that are not features of the library (the hand-written selector and loop, the object[] dump, the Select and shaping variants, Dapper's variants), because understanding them matters.

The data is traceable and regenerable.

  • Nine SVGs in docsite/images/perf/, each with alt text and its own background card so it reads in light and dark. Per-bar hover details are SVG <title> elements (a static stand-in for tooltips).
  • A new page, performance-data.md, has one readable table per chart, a provenance table (run date, build, machine) and a download link for each CSV; every chart links to its table's anchor.
  • The CSVs are built from BenchmarkDotNet's own exported report files by docsite/tools/perf/Extract-PerfData.ps1, and New-PerfCharts.ps1 generates the SVGs and the data page from the CSVs. Each CSV has a .source.txt naming the build, date, machine and result file. Every charted number was re-derived from those files and matched; a second generator run leaves the tree unchanged. The README there has an "Updating the performance charts" section: per chart the benchmark classes and filters, the environment variables, the commands and the expected time.
  • Not on the page: anything marked "still to measure", the console-probe figures (the how-to carries those), and claims that nothing in the new result files traces to.

The standalone ranking page (ranking.html) stays as a clearly labelled snapshot ("Interactive ranking (snapshot)" in the menu, under Performance, next to "Performance data"). The tip box at the top of performance.md is removed, since the page is now the charts.

This merges only with fresh data. The charts are built and reviewed on the existing results (all runs 2026-11-14, AMD Ryzen 9 7900, .NET 11.0.0, before 11.0.0-rc.6). The owner's rule is that only up-to-date data is published, so this PR merges only after the charts are regenerated from a fresh run on current master (about 59 minutes in total from the README's list, or the scoped plan of about 26 minutes). That is stated in the README, on the data page and here.

Checks

  • DocFX builds with 0 warnings and 0 errors (before and after bringing master in), and the built site has all nine SVGs and the ten data files; every relative link in both pages resolves.
  • The charts were checked in light and dark and at phone width.
  • Leak scan clean.

🤖 Generated with Claude Code

electricessence and others added 3 commits November 16, 2026 11:13
…rs live in CSV files and a data page

The page now opens with a chart and each section is chart, explanation,
then a link to its data: headline ratios, reader-open time, total time,
memory, cost against columns, the one-time cost of a map, real databases
(time and memory) and sync against async reads. The general text (what is
measured, limits) moved to the end.

Numbers are in docsite/perf-data/*.csv, one per chart set, each with a
source file naming the benchmark, build, run date, machine, conditions and
the BenchmarkDotNet result file of every number. The SVGs and the new data
page (performance-data.md, one table per chart plus provenance) are
generated from those CSVs by docsite/tools/perf/New-PerfCharts.ps1;
Extract-PerfData.ps1 builds the CSVs from a run's own BenchmarkDotNet
exports. The README beside them lists how to update the charts. DocFX
publishes the CSVs (resource entry added).

The data comes from the runs of 2026-11-14, before rc.6, one run per case.
It is to be replaced by a fresh run on current master before this merges.

Docs and docs tooling only: no Source or PublicAPI change.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Keeps both resource entries (perf-data and benchmarks). The Performance
page is now the chart page, so the tip box that linked the standalone
ranking page is gone; that page stays as a labelled snapshot, linked
from the end of Performance and from the menu under Performance, next
to the new data page.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…on a phone

Bars are solid in the family colors of the benchmark ranking page (its
light and dark sets), rounded at the data end, with no outline. Each chart
sits in a container that scrolls horizontally, with the SVG at a minimum
width of 560 px (its own width), so its text stays at 11.5 px or more on
a narrow screen. The SVGs still draw their own background card. Regenerated
with the committed scripts; the CSV files are unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@electricessence
electricessence marked this pull request as ready for review November 16, 2026 19:27
@electricessence
electricessence merged commit a3be24c into master Nov 16, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant