Readme.md? We Can Do Better
summary
Argues that README.md files become more useful when replaced or supplemented with executable Jupyter/IPYNB README pages that contain runnable cells, shell commands, multi‑language kernels and saved outputs. Demonstrates a live to‑do demo, a Dockerized fork of git history analysis via codem that surfaces surprising file coupling, and tree‑sitter queries that extract class names into scripts. Notes GitHub renders IPYNB but won’t execute cells, VS Code + Jupyter extension does, and CI can refresh outputs.
AI-written summary · about
chapters (10)
- 0:00Introduction
- 3:31Writing docs is hard
- 6:22Three types of docs
- 7:48Markdown’s non-standard status
- 13:13Jupyter notebooks
- 15:50Jupyter notebook demo
- 21:47Git history with CodeMaid
- 25:00LLMs and IPMD workflows
- 28:35Literate programming with notebooks
- 31:02Q&A
related talks
34mCode the Docs: Interactive Document Environments
49mUntitled13.ipynb
01h 44mLeveling up your Jupyter notebook skills
17mNotes on Notebooks: Is Jupyter the Bringer of Jollity?
28mUnlock the Full Potential of Jupyter Notebooks
28mCode the Docs: Interactive Document Environments
33mSignificant Roadblocks to Usefulness for Jupyter Notebooks and a Recipe to Fix them
35mThe Art of Documentation and Readme.md for Open Source Projects