Idea: a shared glossary of technical concepts and terms, held once in the pool

Aperta
  • Qualcosa non va?
#3 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
30/100
Tipo di issue
Funzionalità
Chiarezza
Da chiarire
Stato di attività
Tranquilla
Stack tecnologico
python
Ambito
build-system, content, documentation

Direzione di ricerca

Inizia leggendo il layout del pool, il modello di manifest per prodotto e la toolchain _base; l’issue identifica inoltre come contesto file duplicati quali ifp_egm.md e _static/quant-econ.bib. Il lavoro è completato quando è stata concordata una direzione per il posizionamento del glossario, l’inclusione per prodotto, la risoluzione dei riferimenti incrociati e la sequenza successiva o parallela al pilota dp.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Carried over from QuantEcon/meta#141, which proposed a centralised set of explanations that lectures across every series could reference. That issue is closed; the idea belongs here, because the pool model is what makes it possible.

The idea

A glossary of technical concepts and terms, held once in the pool, that any lecture in any product can reference. Not a lecture and not a series — a set of short, linkable definitions for the vocabulary our lectures assume: contraction mapping, Domar weight, ergodicity, Leontief inverse, spectral radius, stationarity, tail index, and so on.

The reader-facing goal is that a lecture can say "we assume the operator is a contraction" and link the word, rather than either re-explaining it or assuming it.

Why this belongs to the monorepo rather than to a series

Today an explanation can only live inside one series. If a concept is used in four series, the options are to explain it four times, to explain it once and have the other three link across to a different site, or to assume it. All three are bad, and the duplication is already visible in the live repos:

  • ifp_egm.md exists in lecture-python.myst, lecture-dp and lecture-jax
  • cross_product_trick.md exists in lecture-python.myst and lecture-dp
  • wealth_dynamics.md exists in lecture-python.myst and lecture-jax
  • _static/quant-econ.bib is duplicated across at least eight repositories

That is the exact problem the pool is designed to remove: hold the canonical thing once, and let each product select it. A glossary is the smallest, lowest-risk instance of that principle — a glossary entry has no execution, no dependencies and no figures, so it is far cheaper to share than a lecture is.

It is also a genuine argument for the pool. If the monorepo can hold one definition of "contraction mapping" that four products reference, that is a capability none of the six live series can offer today, rather than a reorganisation of something they already do.

Open questions

  • Where in the layout? A glossary is pool content, but it is not a lecture. Does it live under lectures/ alongside the pool, under _base/ as shared infrastructure, or in a sibling directory of its own?
  • Per-product inclusion. Does every product get the whole glossary, or does a product manifest select the subset its lectures actually reference? The latter fits the manifest model but means the glossary needs per-entry granularity.
  • Referencing mechanism. MyST cross-references work within a build. A pool glossary referenced from several products needs the reference to resolve inside each product's build, which is a question for the _base toolchain rather than for the content.
  • Sequencing. This is post-cutover work by definition — it cannot be mirrored from upstream, because no upstream series has one. Worth deciding whether it waits for the dp pilot to prove the pool, or whether a glossary is small enough to be a useful second pilot in its own right.

Not proposed here

The original issue also floated a public subdomain for this material — concepts.quantecon.org, resources.quantecon.org and similar. None of those exist and none are proposed now. If a glossary ships, whether it is a product with its own URL or a shared component included in other products is a later question.

Filed as an idea for the roadmap, not as scheduled work.

Lingua principale
Python
Stelle
1
Fork
0
Merge medio
1g 3h
PR unite (30g)
17

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di QuantEcon/lectures

Tutte le issue di QuantEcon/lectures

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.