Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

docs: add a "Use the data" section and docs/data.md so the exports, field reference and citation are discoverable; add the credit line to catalog.csv

Fechada
  • Algo errado?
#142 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
52/100
Tipo de issue
Documentação
Clareza
Claramente especificada
Status de atividade
Ativa
Stack de tecnologia
javascript, json, markdown
Domínio
content, documentation

Direção de pesquisa

Start with README.md, site/README.md, the export generation code for catalog.csv and the site footer template. Check data.json keys and the current CITATION.cff before writing the field reference and citation examples. Add the README entry point, docs/data.md, CSV columns and footer links; done when exports are discoverable from the README and site pages, the field list matches data.json, and catalog.csv includes the credit line.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

documentation priority: high

Why it matters

The exports are the catalog's second product, and the audience of #115 (MCP/CLI), of Google Dataset Search (JSON-LD from #74) and of anyone deciding whether to cite or sponsor. Today they are documented only in the developer file site/README.md, which a visitor would not open, and neither the README nor any site page links to them.

Evidence (at 69387df)

  • README.md never mentions data.json, catalog.csv, feed.xml, reverified.xml, llms.txt, Releases or CITATION.cff. ROADMAP.md:33-34 is the only top-level mention.
  • The homepage has no visible link to any export: the only references are the two <link rel="alternate"> feed tags in site/lib/shared.mjs:239-240. The footers in site/lib/category-page.mjs:54-60, entry-page.mjs:164-170 and freshness.mjs:138-142 carry credit, sponsor and a build stamp, nothing else.
  • The field reference at site/README.md:32-50 omits licenseFamily (present on every data.json entry) and names the stats object without describing it.
  • catalog.csv header: id,name,url,category,license,license_spdx,commercial,attribution_required,formats,tags,added,verified,status,page. No publisher, subcategories, attribution_string or summary, so the one field a shipping developer most needs from a spreadsheet, the credit line, is missing.
  • Nothing explains the two caveats a consumer must carry: that verified is a read date not a validity guarantee (said once at site/README.md:49-50), and that license is the catalog's reading, not the source's SPDX expression.

Suggested approach

Add a short README section "Use the data" (the five URLs, the Releases link, a pointer to docs/data.md) and a docs/data.md with: file list and purpose, the full field table (moved out of site/README.md, leave a pointer), three copy-paste examples (curl + jq for "all CC0 audio with no credit", a 6-line pandas snippet, a feed-reader URL), the caveats paragraph, a stability promise ("field names are stable; optional fields may appear"), and a "How to cite" block rendering CITATION.cff as APA and BibTeX. Add attribution_string, publisher and subcategories columns to the CSV. Put a one-line "Data: JSON / CSV / feeds / llms.txt" link in the site footer template.

Done when

A first-time visitor can find and understand every export from the README and from any site page without opening site/; site/README.md field list matches data.json keys; catalog.csv includes the credit line.

Linguagem predominante
JavaScript
Estrelas
58
Forks
15
Merge médio
16h 53min
PRs com merge (30d)
14

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de TMHSDigital/Free-Game-Dev-Assets

Todas as issues de TMHSDigital/Free-Game-Dev-Assets

Issues semelhantes

Mais issues de JavaScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.