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

Abierto
  • ¿Algo no está bien?
#3 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
30/100
Tipo de issue
Nueva funcionalidad
Claridad
Necesita aclaración
Estado de actividad
Tranquilo
Stack tecnológico
python
Área
build-system, content, documentation

Línea de trabajo

Empieza leyendo el diseño del pool, el modelo de manifiesto por producto y la toolchain _base; el issue también identifica archivos duplicados como ifp_egm.md y _static/quant-econ.bib como contexto. Se considera terminado cuando haya una dirección acordada para la ubicación del glosario, la inclusión por producto, la resolución de referencias cruzadas y la secuenciación después o junto con el piloto de dp.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Python
Estrellas
1
Forks
0
Merge medio
1 d 3 h
PR fusionados (30 d)
17

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de QuantEcon/lectures

Todos los issues de QuantEcon/lectures

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.