Skip to content

Contributing

Thanks for helping make these summaries better. This repo is documentation only - no code to build, just clear writing about AI: summaries of influential papers and essays, plus explainers on the things no single paper covers.

Adding a new paper summary

  1. Pick a category under papers/: architectures, language-models, image-generation (image, video and 3D), multimodal (including audio), robotics, techniques, or essays (landmark essays and blog posts that shaped the field - same format, with **Essay:** or **Post:** as the link line).
  2. Create a folder named NN-slug where NN is the next free two-digit number (numbers are stable IDs, not a strict chronology - just don't reuse one) and slug is a short kebab-case name. Example: papers/techniques/64-my-paper/.
  3. Copy the template: start from papers/_TEMPLATE.md and save it as summary.md inside your new folder.
  4. Keep the header intact. The first lines must be the # Title and a metadata block with **Authors:**, **Published:**, and a link line (**Paper Link:**, **Paper:**, **System Card:**, etc.). The build script parses these.
  5. Do not hand-write YAML frontmatter - it is generated (see below).
  6. Add a card to BROWSE.md. Every paper has one, in its category section, ordered by number: a relevance badge, three lines of pitch and a link to the source. Update that section's "N papers." line, the Quick Stats table and the badge tallies at the foot of the page to match.
  7. Add the paper to the coverage map in docs/GAPS.md, and bump its "Papers at review time" figure. If the paper closes a queued gap, delete that queue entry.
  8. Add a row to docs/QUICK_REFERENCE.md - one line each for the contribution and the impact. The other guides curate rather than enumerate, so update them only if the paper belongs on a learning path or changes a comparison.
  9. Run the build script and the checks, and commit what they change:
python3 scripts/build_manifest.py
python3 scripts/check_links.py
python3 scripts/check_counts.py

check_counts.py is what catches a forgotten BROWSE card or a stale tally; CI runs the same three.

Adding an explainer

Explainers cover what is not one paper: a model family's lineage, a benchmark family, the economics of compute, a policy, an open debate. They live in explainers/<section>/<slug>.md and are unnumbered.

  1. Pick a section: history, model-families, benchmarks, concepts, compute, policy, ecosystem, or open-questions. A new section means adding it to EXPLAINER_SECTIONS in scripts/build_manifest.py.
  2. Copy explainers/_TEMPLATE.md and keep its three header lines: # Title, **In one line:** and **Last reviewed:** YYYY-MM-DD. check_counts.py fails CI without them; build_manifest.py lists the page in the generated EXPLAINERS.md and the site nav from them.
  3. Link down, do not re-summarise. Point at the paper summaries for detail, and at the Learn concept pages and Build projects for hands-on material.
  4. Date every moving fact ("as of September 2026") and source it. When you re-check a page, bump its Last reviewed date. The build prints a warning for any explainer not reviewed in 180 days.

No BROWSE card, manifest entry or GAPS row is needed for an explainer.

House style

  • Write for a motivated beginner. Explain jargon the first time it appears.
  • Lead with why the paper matters before the mechanics.
  • Use concrete analogies and small diagrams or formulas in fenced code blocks.
  • Be accurate with numbers, dates, and author lists. Cite the real paper.
  • Cross-link sibling summaries in this repo where one paper builds on another.
  • No em dashes. Use regular hyphens.

What the build script does

scripts/build_manifest.py is the single source of truth for metadata. It is idempotent - safe to run any time. On each run it:

  • (re)writes YAML frontmatter (including topic tags:) on every summary.md,
  • regenerates papers.json and papers.csv (machine-readable manifests),
  • regenerates INDEX.md (category browse index) and TAGS.md (topic browse index),
  • writes mkdocs.generated.yml - the hand-maintained mkdocs.yml plus the generated site navigation, and
  • assembles the git-ignored site-build/ tree the site is built from, including the site-only landing page and stylesheet from .github/site/.

mkdocs.yml itself is hand-maintained and deliberately carries no nav key. Edit it for theme, palette, or markdown extensions; edit write_mkdocs() in build_manifest.py for the navigation. Both mkdocs.generated.yml and site-build/ are git-ignored - never commit or hand-edit them.

A separate script, scripts/measure_sources.py, measures how many words of source material the summaries stand in for. It is the only script that touches the network and is deliberately not part of the pipeline: it caches its results in source_lengths.json, which build_manifest.py then reads offline. Run it after adding papers:

python3 scripts/measure_sources.py   # needs pdftotext (poppler-utils)

It counts every word pdftotext extracts from each paper's PDF and skips sources with no retrievable PDF rather than estimating them, so the figure published on the landing page is a floor. Do not hand-edit those numbers.

A companion script, scripts/add_cross_links.py, regenerates the "Related in This Collection" footers. When you add a paper, also add an entry to the TOPICS map in build_manifest.py and the ALIASES map in add_cross_links.py. Both scripts use only the Python standard library.

Previewing the site locally

python3 -m venv .venv-docs
.venv-docs/bin/pip install -r requirements.txt
python3 scripts/build_manifest.py
.venv-docs/bin/mkdocs serve -f mkdocs.generated.yml

Then open http://127.0.0.1:8000.

Before pushing anything that touches the site, run the build the way CI does:

python3 scripts/build_manifest.py
.venv-docs/bin/mkdocs build -f mkdocs.generated.yml --strict

--strict turns every MkDocs warning into an error, so a broken relative link or a link to an anchor that does not exist fails the build rather than shipping a broken page. One trap: on the site, README.md is replaced by the landing page in .github/site/home.md, so a link to README.md#some-anchor resolves on GitHub but fails the strict build. Link to the page without the anchor, or to INDEX.md. The same build runs as a blocking check on every pull request; pushing to main also deploys it to GitHub Pages via .github/workflows/pages.yml.