{"course":{"slug":"hugging-face","title":"Hugging Face, End to End","url":"https://addaly.com/learn/hugging-face","level":"intermediate","track":"create"},"lesson":{"slug":"the-card-that-passes-review","title":"Writing a card somebody can audit","url":"https://addaly.com/learn/hugging-face/the-card-that-passes-review","position":73,"of":75,"minutes":9,"answer":"A card written for an auditor (documented data, stated intended and out-of-scope use, measured evaluation against a baseline with per-group results.","keyIdea":"A card written for an auditor (documented data, stated intended and out-of-scope use, measured evaluation against a baseline with per-group results, a specific named limitation and a contact) is also the card a careful user needs, and it is the practice that survives whatever the specific regulation turns out to be."},"body":{"format":"markdown","text":"## Two audiences, one document\n\nA model card is read by somebody deciding whether to use your model, and, increasingly, by somebody asking how a system in production was built. The second reader is new, and they ask harder questions: what was it trained on, how was it tested, who is accountable, what does it do to people it was not designed for.\n\nWriting for the second reader improves the document for the first, because the questions are the same ones a careful user has and does not ask.\n\n## The structure\n\n**Front matter that is correct.** `license`, `base_model`, `language`, `datasets`, `pipeline_tag`, `library_name`. These are indexed, they make your work findable, and a wrong `pipeline_tag` means nobody filtering for your task ever sees it.\n\n**One paragraph: what it is and what it is for.** No marketing. \"A LoRA adapter for Qwen2.5-7B-Instruct that classifies Hindi and English customer support messages into nine intents.\"\n\n> Figure: Two limitation sections. True of everything: May produce inaccurate output; Use with caution; Performance may vary by input; Not suitable for all use cases. Specific, and free to write: Accuracy on Hindi is eight points below English; Trained on one company's support queue in 2024; Untested on Hinglish code-switching, common here; Word error rate roughly doubles on phone audio; Not for deciding anything about a person unreviewed. The left column is true of every model ever released and therefore informs nobody. The right column costs an afternoon of your own testing, which you have already done, and it is the section most likely to stop somebody misusing your work.\n\n**A runnable snippet.** With the revision pinned. Test it in a fresh environment before publishing: the commonest defect in cards is a snippet that never ran.\n\n**Intended use, and out-of-scope use.** The second is the one people skip and the one that protects everybody. \"Not for medical, legal or financial advice. Not evaluated on languages other than Hindi and English. Not suitable for deciding anything about a person without human review.\"\n\n**Training data.** Source, size, date range, languages, how it was collected, and whether it contained personal data. If you cannot publish the dataset, describe it. A card that says nothing about data is a card that cannot be assessed.\n\n**Training procedure.** Base model and revision, method, hyperparameters, hardware, duration. Six lines, and they are what makes your work reproducible rather than anecdotal.\n\n**Evaluation.** What you measured, on what, against what baseline. A number without a baseline means nothing; a number without a described set means less.\n\n**Limitations and bias.** This is the section that separates a card from a README, and it has to be specific. Not \"may produce biased output\", which is true of everything and informs nobody, but \"accuracy on Hindi messages is 8 points below English; the training data came from one company's support queue in 2024 and skews toward delivery complaints; the model has not been tested on Hinglish code-switching, which is common in this domain.\"\n\n**Environmental cost**, if you can compute it. Hardware, hours, and where it ran. One line.\n\n**Contact.** A discussion tab is enough, but say so.\n\n## Per-group results, where they apply\n\nIf your model touches people, one overall number hides what matters. Report the metric separately by whatever groups your data supports: language, region, input length, customer type. A model at 0.89 overall may be at 0.93 on English and 0.71 on Hindi, and the second pair of numbers is the whole story for a service whose users are mostly Hindi speakers.\n\nYou can only report groups your data records. That is itself a finding worth stating: \"we could not measure performance by region because region is not recorded\" is honest and useful.\n\n## What regulation is starting to ask for\n\nRules are arriving at different speeds in different places. The European Union's AI Act introduces obligations that vary by risk category and by whether you are a provider or a deployer, with documentation and transparency duties among them. Other jurisdictions are drafting, consulting or doing nothing. Sectoral rules (medical devices, financial advice, employment decisions) often bite before any AI-specific law does.\n\nThe honest summary is that the obligations differ by where you are, what the system does, and who uses it, and that this is moving. **Nothing here is legal advice.** What generalises is the practice: a documented dataset, a stated intended use, a measured evaluation with per-group results, a named limitation and a way to contact somebody. A team that has those can answer whatever the specific requirement turns out to be. A team that has none of them is starting from nothing whenever somebody asks.\n\n## The test\n\nGive the card to somebody who has not seen the project. Ask them: what does it do, what will it do badly, can they run it in ten minutes, and would they be comfortable if it were used on them. Those four questions catch nearly everything.\n\n## Do this now\n\nOpen your best existing card and write the out-of-scope section, specifically, from your own testing. It is the section you can write today with information you already have, and it is the one most likely to stop somebody misusing your work."},"check":{"question":"A card's limitations section reads \"this model may reflect biases present in its training data\". Why is this close to useless?","options":[{"text":"It admits a flaw without proposing a mitigation, which readers interpret as an unresolved defect.","correct":false,"tempting":"Mitigations are welcome but a card's job is first to describe accurately."},{"text":"Bias claims require statistical evidence, so an unquantified statement is not defensible under most documentation standards.","correct":false,"tempting":"Appeals to a standard rather than to what the sentence fails to tell a reader."},{"text":"It is true of every model, so it transfers no information about this one.","correct":true},{"text":"It shifts responsibility onto the dataset's authors, which the model's publisher cannot do.","correct":false,"tempting":"Reads it as an attribution of blame when the problem is that it says nothing specific at all."}]},"prev":{"slug":"publishing-your-own","title":"Publish it so a stranger can use it without writing to you","url":"https://addaly.com/learn/hugging-face/publishing-your-own"},"next":{"slug":"contributing-back","title":"Pull requests, discussions and being useful","url":"https://addaly.com/learn/hugging-face/contributing-back"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Exam keys checked blind by a second model: 3,665 of 3,666 agreed. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'Writing a card somebody can audit', in Hugging Face, End to End. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/hugging-face/the-card-that-passes-review (Accessed: 13 October 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"Writing a card somebody can audit","courseTitle":"Hugging Face, End to End","module":{"index":8,"slug":"depending-on-it-and-publishing","title":"Depending on it, and publishing so others can"},"answer":null,"keyIdea":"A card written for an auditor (documented data, stated intended and out-of-scope use, measured evaluation against a baseline with per-group results, a specific named limitation and a contact) is also the card a careful user needs, and it is the practice that survives whatever the specific regulation turns out to be.","hero":{"kind":"figure","figure":{"t":"figure","label":"Figure","figure":{"left":{"title":"True of everything","items":["May produce inaccurate output","Use with caution","Performance may vary by input","Not suitable for all use cases"]},"type":"compare","right":{"title":"Specific, and free to write","items":["Accuracy on Hindi is eight points below English","Trained on one company’s support queue in 2024","Untested on Hinglish code-switching, common here","Word error rate roughly doubles on phone audio","Not for deciding anything about a person unreviewed"]},"title":"Two limitation sections","caption":"The left column is true of every model ever released and therefore informs nobody. The right column costs an afternoon of your own testing, which you have already done, and it is the section most likely to stop somebody misusing your work."},"alt":"Figure: Two limitation sections. True of everything: May produce inaccurate output; Use with caution; Performance may vary by input; Not suitable for all use cases. Specific, and free to write: Accuracy on Hindi is eight points below English; Trained on one company’s support queue in 2024; Untested on Hinglish code-switching, common here; Word error rate roughly doubles on phone audio; Not for deciding anything about a person unreviewed. The left column is true of every model ever released and therefore informs nobody. The right column costs an afternoon of your own testing, which you have already done, and it is the section most likely to stop somebody misusing your work."}},"blocks":[{"t":"h2","id":"two-audiences-one-document","runs":[{"text":"Two audiences, one document"}]},{"t":"p","runs":[{"text":"A model card is read by somebody deciding whether to use your model, and, increasingly, by somebody asking how a system in production was built. The second reader is new, and they ask harder questions: what was it trained on, how was it tested, who is accountable, what does it do to people it was not designed for."}]},{"t":"p","runs":[{"text":"Writing for the second reader improves the document for the first, because the questions are the same ones a careful user has and does not ask."}]},{"t":"h2","id":"the-structure","runs":[{"text":"The structure"}]},{"t":"p","runs":[{"text":"Front matter that is correct.","b":true},{"text":" "},{"text":"license","code":true},{"text":", "},{"text":"base_model","code":true},{"text":", "},{"text":"language","code":true},{"text":", "},{"text":"datasets","code":true},{"text":", "},{"text":"pipeline_tag","code":true},{"text":", "},{"text":"library_name","code":true},{"text":". These are indexed, they make your work findable, and a wrong "},{"text":"pipeline_tag","code":true},{"text":" means nobody filtering for your task ever sees it."}]},{"t":"p","runs":[{"text":"One paragraph: what it is and what it is for.","b":true},{"text":" No marketing. “A LoRA adapter for Qwen2.5-7B-Instruct that classifies Hindi and English customer support messages into nine intents.”"}]},{"t":"p","runs":[{"text":"A runnable snippet.","b":true},{"text":" With the revision pinned. Test it in a fresh environment before publishing: the commonest defect in cards is a snippet that never ran."}]},{"t":"p","runs":[{"text":"Intended use, and out-of-scope use.","b":true},{"text":" The second is the one people skip and the one that protects everybody. “Not for medical, legal or financial advice. Not evaluated on languages other than Hindi and English. Not suitable for deciding anything about a person without human review.”"}]},{"t":"p","runs":[{"text":"Training data.","b":true},{"text":" Source, size, date range, languages, how it was collected, and whether it contained personal data. If you cannot publish the dataset, describe it. A card that says nothing about data is a card that cannot be assessed."}]},{"t":"p","runs":[{"text":"Training procedure.","b":true},{"text":" Base model and revision, method, hyperparameters, hardware, duration. Six lines, and they are what makes your work reproducible rather than anecdotal."}]},{"t":"p","runs":[{"text":"Evaluation.","b":true},{"text":" What you measured, on what, against what baseline. A number without a baseline means nothing; a number without a described set means less."}]},{"t":"p","runs":[{"text":"Limitations and bias.","b":true},{"text":" This is the section that separates a card from a README, and it has to be specific. Not “may produce biased output”, which is true of everything and informs nobody, but “accuracy on Hindi messages is 8 points below English; the training data came from one company’s support queue in 2024 and skews toward delivery complaints; the model has not been tested on Hinglish code-switching, which is common in this domain.”"}]},{"t":"p","runs":[{"text":"Environmental cost","b":true},{"text":", if you can compute it. Hardware, hours, and where it ran. One line."}]},{"t":"p","runs":[{"text":"Contact.","b":true},{"text":" A discussion tab is enough, but say so."}]},{"t":"h2","id":"per-group-results-where-they-apply","runs":[{"text":"Per-group results, where they apply"}]},{"t":"p","runs":[{"text":"If your model touches people, one overall number hides what matters. Report the metric separately by whatever groups your data supports: language, region, input length, customer type. A model at 0.89 overall may be at 0.93 on English and 0.71 on Hindi, and the second pair of numbers is the whole story for a service whose users are mostly Hindi speakers."}]},{"t":"p","runs":[{"text":"You can only report groups your data records. That is itself a finding worth stating: “we could not measure performance by region because region is not recorded” is honest and useful."}]},{"t":"h2","id":"what-regulation-is-starting-to-ask-for","runs":[{"text":"What regulation is starting to ask for"}]},{"t":"p","runs":[{"text":"Rules are arriving at different speeds in different places. The European Union’s AI Act introduces obligations that vary by risk category and by whether you are a provider or a deployer, with documentation and transparency duties among them. Other jurisdictions are drafting, consulting or doing nothing. Sectoral rules (medical devices, financial advice, employment decisions) often bite before any AI-specific law does."}]},{"t":"p","runs":[{"text":"The honest summary is that the obligations differ by where you are, what the system does, and who uses it, and that this is moving. "},{"text":"Nothing here is legal advice.","b":true},{"text":" What generalises is the practice: a documented dataset, a stated intended use, a measured evaluation with per-group results, a named limitation and a way to contact somebody. A team that has those can answer whatever the specific requirement turns out to be. A team that has none of them is starting from nothing whenever somebody asks."}]},{"t":"h2","id":"the-test","runs":[{"text":"The test"}]},{"t":"p","runs":[{"text":"Give the card to somebody who has not seen the project. Ask them: what does it do, what will it do badly, can they run it in ten minutes, and would they be comfortable if it were used on them. Those four questions catch nearly everything."}]},{"t":"h2","id":"do-this-now","runs":[{"text":"Do this now"}],"role":"try"},{"t":"p","runs":[{"text":"Open your best existing card and write the out-of-scope section, specifically, from your own testing. It is the section you can write today with information you already have, and it is the one most likely to stop somebody misusing your work."}]}],"check":{"question":[{"text":"A card’s limitations section reads “this model may reflect biases present in its training data”. Why is this close to useless?"}],"options":[{"text":[{"text":"It admits a flaw without proposing a mitigation, which readers interpret as an unresolved defect."}],"correct":false,"tempting":[{"text":"Mitigations are welcome but a card’s job is first to describe accurately."}]},{"text":[{"text":"Bias claims require statistical evidence, so an unquantified statement is not defensible under most documentation standards."}],"correct":false,"tempting":[{"text":"Appeals to a standard rather than to what the sentence fails to tell a reader."}]},{"text":[{"text":"It is true of every model, so it transfers no information about this one."}],"correct":true,"tempting":null},{"text":[{"text":"It shifts responsibility onto the dataset’s authors, which the model’s publisher cannot do."}],"correct":false,"tempting":[{"text":"Reads it as an attribution of blame when the problem is that it says nothing specific at all."}]}],"order":[3,0,1,2],"why":null},"prev":{"slug":"publishing-your-own","title":"Publish it so a stranger can use it without writing to you","minutes":10},"next":{"slug":"contributing-back","title":"Pull requests, discussions and being useful","minutes":8}}}