This site’s existing tutorial on auditing a weights repo’s licence is about reading someone else’s documentation critically. This one is about writing your own — specifically, the model card: the single document meant to tell a developer whether to build on your model, a researcher whether they can reproduce it, and someone affected by its output what it was actually trained and evaluated to do.
Why “boundary object” is the right frame
Hugging Face’s own Model Card Guidebook describes the goal explicitly: a model card should work as a “boundary object” — one artifact that stays useful across audiences with completely different backgrounds and goals, from the engineer deciding whether to fine-tune on top of your weights to a policymaker trying to understand what the model does at all. That’s a genuinely hard brief, and it’s why a model card that’s just a benchmark table and a license badge is usually failing most of its readers, even if it’s technically complete.
The sections that actually carry weight
A real model card is organized around a handful of sections that each answer a different reader’s question, not a single wall of text:
- Model description: what architecture, what it was designed to do, and — critically — what it was not designed to do. This is the section most often skipped, and it’s the one that prevents the most misuse.
- Training data: what the model actually saw. Vague (“a large, diverse web corpus”) is common and mostly worthless; specific (named datasets, licence terms per dataset, collection dates, known gaps) is what makes the card usable for anyone trying to assess bias or provenance.
- Evaluation: name the actual benchmark, the actual split, the actual metric, and the actual number — not just “performs well.” A reader can’t act on an unnamed benchmark, and can’t reproduce an unspecified split.
- Bias, risks, and limitations: by Hugging Face’s own user research, this is consistently the section teams find hardest to write — and it’s exactly the section a model card exists to force into the open rather than leaving undocumented. List concrete failure modes you’ve actually observed, not a generic disclaimer.
- Environmental impact: increasingly standard practice for larger training runs — compute used, hardware, estimated CO2, with a pointer to how it was estimated.
Use the template, don’t start from a blank page
Hugging Face ships an actual model card template inside the huggingface_hub library (modelcard_template.md), plus an Annotated Model Card that explains what belongs in each section line by line, and a no-code Model Card Creator Tool for teams who want to split the writing work without everyone needing to touch Markdown directly. Starting from that template rather than a blank README is the single fastest way to avoid the two failure modes above: sections that get skipped because nobody thought to add them, and sections that exist but say nothing specific enough to act on.
The habit this pairs with
If you’ve run this site’s model-licence-audit tutorial against someone else’s repo, you already know what a thin card looks like from the reader’s side — a licence field with nothing behind it, an evaluation claim with no named benchmark, a training-data description too vague to assess. Writing your own card well is the other half of that same discipline: hold your own documentation to the standard you’d want when auditing someone else’s.