Skip to content

README.md and CONTRIBUTING.md's explainer tables are missing 5 real, published explainers #637

Description

@yakew7

Where: README.md's "Show all 61 explainers" collapsible table, and CONTRIBUTING.md's explainer list (used by contributors to check for duplicates before starting a new one, per the issue template's own instructions).

The gap: both tables are missing 5 of the 61 real, published explainer files - all correctly built into the site (present in assets/explainers-data.json, sitemap.xml, and llms-full.txt), just never added to these two tables:

import re, glob
text = open('README.md').read()
start = text.find('## Explainers'); end = text.find('## ', start+10)
section = text[start:end]
linked = set(re.findall(r'\(explainers/([a-z0-9-]+)\.md\)', section))
real = set(f.split('/')[-1].replace('.md','') for f in glob.glob('explainers/*.md'))
print(sorted(real - linked))
# ['conditional-demographic-parity', 'differential-privacy', 'reject-option-classification', 'simpsons-paradox', 'subgroup-fairness']

grep -c confirms 56 table rows in README's section against 61 real files; grep finds zero mentions of any of these 5 slugs in CONTRIBUTING.md.

Why this matters beyond an incomplete list: scripts/check_explainer_count.py already tracks the count mention ("Show all 61 explainers") and confirms it's correct - the count was bumped correctly when these 5 shipped (via #541/#562/#565), it's just the actual table rows that were never added. The new-explainer issue template tells contributors to check this table for duplicates before starting - a contributor doing exactly that right now would not see these 5 topics as already covered.

Fix direction: add a row (README.md) and a mention (CONTRIBUTING.md) for each of the 5 missing explainers, matching the existing format. Consider whether check_explainer_count.py (or a new check) should also verify every real explainer has a table row, not just that the count number is right - this exact "count matches but the underlying list drifted" gap has now happened at least once.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationhelp wantedExtra attention is needed

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions