A register of model documentationSETTING THE ISSUE…

CALAPHON

@calaphon
The register is not answering.
Method

How the register is set, and what it cannot see.

Everything below can be reproduced with curl and no account. Where the method is weak, this page says so rather than leaving it to be found.

The procedure

  1. 01
    Take a slice of the download ranking

    Each issue asks the Hugging Face API for models ordered by downloads, walking in slices and looping through the top few hundred. Ordering by usage, not upload date, is deliberate — see the note below.

  2. 02
    Fetch the card

    One request per model for README.md on the main branch. A 404 is an answer, not an error: it means the repository has no card, which is precisely what the rubric is asking about.

  3. 03
    Strip the front-matter

    The YAML block at the top is removed before the card is measured, so a long metadata header cannot pass as a substantial document.

  4. 04
    Apply the nine marks

    Each mark asks whether a licence is named or a heading exists. No mark asks whether a passage is good enough — that judgement is exactly what would let us tilt a result.

  5. 05
    File it, or revise it

    A new model gets a permanent entry number. A model already filed is re-scored, and if the score moved, the entry is stamped as revised with both figures kept.

  6. 06
    Withhold if thin

    No proportion is printed anywhere below the floor entries, and no publisher is ranked on fewer than 3.

Read this part

What this register cannot see

Documentation that lives elsewhere

Several labs publish limitations in a separate paper and keep the repository lean. The rubric marks the repository, so those models score lower here than their publisher's total effort deserves. That is still a real loss to somebody who downloads the weights and never finds the paper — but it is not the same thing as never having written it.

Headings we did not think of

A card can discuss risk under a heading none of our word lists match, and it will be marked as missing. The lists are printed in full on the rubric page for exactly this reason: they are the part most likely to be wrong, so they are the part most exposed.

Whether any of it is true

A repository claiming an evaluation gets the mark whether or not the evaluation was competent, or happened. This register measures the presence of documentation, never its honesty.

Gated repositories

A card behind an access request is scored as absent. A document a reader cannot open is not documentation for that reader, whatever it says inside.

Models nobody downloads

The register walks the top of the download ranking. Most models on the hub are personal fine-tunes with no users, and marking those undocumented would produce an impressive-looking number that measured nothing. Restricting the sample makes the finding narrower and, we think, worth more.

Movement we have not revisited

Entries are re-scored as the walk loops back around, not continuously. A card improved an hour ago may still be shown at its older score until the register reaches it again.

Reproduce any figure on this site

These are the two requests the register makes. Neither needs a key, an account, or our permission.

# the slice we walk
curl 'https://huggingface.co/api/models?sort=downloads&direction=-1&limit=24'
# the card we read
curl 'https://huggingface.co/mistralai/Mixtral-8x7B-Instruct-v0.1/raw/main/README.md'

Then apply the marks on the rubric page, or let the checker do it and compare its answer to your own.

The station, right now

not answering