Add docs/tech — a technology register for lecture improvements - #6
Merged
Conversation
Records technology options for improving the lectures: what was looked at, where it would apply, and what was decided. The format requires three things per entry, and the middle one is the point: a named file it would apply to. A link on its own decays into nothing. See QuantEcon/meta#53 — a 2022 note pointing at asciinema sat untouched for four and a half years while the thing it would have improved, a 1.4 MB screenshot of a terminal, shipped in a lecture created two years after the note was filed. `declined` is a first-class terminal state requiring a reason and a date, matching the discipline proposed for per-lecture editorial state in QuantEcon/project-monorepo#1 so the two records read together. Seeded with the asciinema entry from the meta triage. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new docs/tech “technology register” to record tooling options considered for improving the lecture corpus, with an explicit focus on where (which files) an option would apply and what decision was made.
Changes:
- Introduces
docs/tech/README.mddefining the register format, required fields, states, and scope. - Adds
docs/tech/index.mdas a one-row-per-entry index. - Seeds the register with an initial declined entry:
docs/tech/entries/asciinema.md.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/tech/README.md | Defines the register’s rules (required sections, states, categories) and contribution process. |
| docs/tech/index.md | Provides a tabular index of written entries for quick scanning/navigation. |
| docs/tech/entries/asciinema.md | First worked entry capturing evaluation context, concrete application sites, and a declined decision. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Declined on the hosting ground — GitHub Pages runs no Python process, and Dash hard-requires Flask with no serverless path (plotly/dash#1559 open since 2021, stale since 2024). The entry is deliberately scoped to Dash-the-framework and carries an explicit warning that it is not about plotly.py figures, which QuantEcon uses and the style guide endorses. It also records what the decision must NOT be read as saying — in particular that "rendering is static HTML" is not the reason, since manual.quantecon.org serves a live interactive plotly figure from GitHub Pages today. Covers the needs-a-server category (Streamlit, Shiny server mode, Panel server mode, Gradio) while explicitly excluding their static-export paths, which are evaluated separately under WASM. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Declined on delivery surfaces, not pedagogy. Mito reaches none of the four surfaces we publish through: it raises an exception in Colab (which getting_started.md recommends and every page links), it paints a dead spreadsheet in the static build at 2.36 MB per cell, its JupyterLab application extension has no shell in our thebe-based live compute, and the downloadable-notebook path needs a labextension install whose one precedent broke in JupyterLab 4. Records what the decision must NOT be read as saying: Mito is alive and shipping, its AGPL move predates the issue, and its telemetry does have a free env-var opt-out. Those three corrections came out of adversarial verification and would otherwise have entered the record wrong. The want was real — itables answers it and is proposed separately in lecture-datascience.myst#282, alongside a stale table PNG open since 2022. The entry says explicitly that interactive tables were not rejected; Mito was. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The "What it is" rule said "one paragraph and a link" and then demanded project health in the same sentence, which does not fit in one paragraph — all three entries broke it. The entries have the right shape, so the rule is what changes: two or three short paragraphs, with health called out because it is what separates a considered decline from a dead-technology one. The index's Applies to column violated the register's own "name files, never areas" rule in its own first row. Tightened the asciinema row to named paths and gave the column a stated contract, so it does not drift back to vague as entries accumulate. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Declined on measured demand and product shape, not cost. QuantEcon ran discourse.quantecon.org from 2016 until March 2025 and retired it for want of users, not want of budget — Hivebrite would reprovision that surface with an invoice attached and still need the staffing whose absence ended the free one. Separately, membership administration assumes a gateable roster; our readership is open and anonymous. Records the current published pricing (Core $895/mo, Flex $1,995/mo billed annually) and warns explicitly that widely-circulated secondary sources quote tiers and figures that do not exist in vendor material — two of three research passes reported those stale numbers. Also records that the non-profit discount exists but is unquantified, and that there is no academic discount, so the next person asking does not have to re-derive it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Creates
docs/tech, a standing record of technology options for improving the lectures — what we looked at, where it would apply, and what we decided.Why
This came out of the QuantEcon/meta issue triage, where a batch of seventeen technology link-shares had accumulated since 2021. QuantEcon/meta#53 is the worked example: a 2022 note pointing at asciinema sat untouched for four and a half years, while the thing it would have improved — a 1.4 MB screenshot of a terminal in
workspace.md— shipped in a lecture created two years after the note was filed. The tool was recorded; the application was not; nobody could act on either.Discussions were the obvious alternative home and they do not work for this. The three link-share discussion buckets in
metahold one, zero and zero comments between them, and a third bucket was opened rather than either of the first two being reused.The format
Three parts per entry, all required. The middle one is the point.
adopted,declinedandsupersededStates are
candidate,evaluating,adopted,declinedandsuperseded.declinedis first-class and terminal: an option we considered and rejected, with the reason written down, is more useful than one that was never recorded — it stops the next person redoing the assessment, and it stops them avoiding the idea without knowing why. That is the same discipline proposed for per-lecture editorial state in QuantEcon/project-monorepo#1, chosen deliberately so the two records can be read together.Revisiting an entry updates the state and appends to the decision section rather than overwriting it. The history of a call is part of the record.
Contents
docs/tech/README.md— purpose, the required parts, states, categories, how to add an entrydocs/tech/index.md— one row per written entrydocs/tech/entries/asciinema.md— the first entry, carried over from Useful Teaching Tool -- Recording Terminal Sessions meta#53The asciinema entry is a decline, and is included precisely because the answer is no: it names three verified application sites, records why a fenced code block beats a hosted player for our one-shot terminal commands, notes that Hugo removed its own
asciicastshortcode in November 2022 after being cited in #53 as the demonstration of the technique, and flags a follow-on worth doing regardless — replacing roughly 1.7 MB of raster terminal screenshots with text, which also fixes an alt-text gap.Notes for review
Paths, pre-cutover. The pool in
lectures/is empty until the per-series cutovers, so entries reference files in the live series repositories using fullowner/repo/pathform. The README says these should be repointed at pool paths as each series moves.No build wiring. Everything is MyST-friendly — YAML frontmatter, plain tables, no GitHub-specific syntax — so
docs/can become a published product later, but this PR adds nomyst.ymland does not touchproducts/. Publishing is a separate, deliberate step.Scope. Technology options for the lectures and the machinery that builds them. Editorial questions about a specific lecture belong with the per-lecture state in QuantEcon/project-monorepo#1, not here.
🤖 Generated with Claude Code