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-jaxcross_product_trick.md exists in lecture-python.myst and lecture-dpwealth_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.
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.mdexists inlecture-python.myst,lecture-dpandlecture-jaxcross_product_trick.mdexists inlecture-python.mystandlecture-dpwealth_dynamics.mdexists inlecture-python.mystandlecture-jax_static/quant-econ.bibis duplicated across at least eight repositoriesThat 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
lectures/alongside the pool, under_base/as shared infrastructure, or in a sibling directory of its own?_basetoolchain rather than for the content.dppilot 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.organd 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.