Skip to content
Ahmad Ammar

6. What to adopt

Ranked by value for the effort. Each item names where it comes from.

6.1 Small and worth doing now

  1. A “report a problem” link on every page (Sphinx book theme’s issues button). A link that opens a GitHub issue already filled in with the page’s address and title. Readers, including students, can then flag a broken step without email.

  2. External link checking in CI (The Turing Way’s lychee workflow). A weekly and per-push job that lists dead links. It needs no TeX, so it is cheap.

  3. Alternative text and file-size checks (The Turing Way). A build check that every figure has a caption or alt text and that no image is larger than a set size. This puts the accessibility rule we already follow into code.

  4. A written build environment (the Sphinx site’s environment.yml, Geocomputation’s dev container). One file listing exactly what the build needs, so another machine, or CI, can build the site.

6.2 Larger, worth planning

  1. Build the guides in CI (R for Data Science, Manubot, the Carpentries). A GitHub Actions job with TeX Live, pandoc and the stack. Browser edits would then publish themselves, and the site would no longer depend on one laptop. Heavy notebooks can keep committed outputs, as Quarto’s _freeze does.

  2. Previews of proposed changes (Geocomputation, The Turing Way). Once CI builds, a pull request can build into a separate preview address, so a change can be read as a page before it goes live.

  3. Versioned, citable releases (The Turing Way with Zenodo). A tagged release of a guide gets a DOI and a CITATION.cff, matching how our data and code are released.

  4. Moving the remaining long documents onto the stack. The Marxian pamphlet and the EGM305 handbook still have their own build scripts; with a document.toml each they would gain the same editing tools.

6.3 What not to copy

Moving from LaTeX to Markdown would make browser editing simpler, but would lose the exact mathematics and print layout that are the point of our sources, and would break the rule that long documents have LaTeX as their one source. MyST and Quarto can both read some LaTeX mathematics, but not our custom environments and macros. The better path is to keep LaTeX and add the checks and CI that these projects show are possible.