// the take
A markdown template for writing design docs for ML systems, based on Eugene Yan's blog post on the topic. It's for ML engineers or teams who want a structured way to think through a project (problem, data, methodology, infra, monitoring, cost) before building, rather than a tool or library.
The section list is genuinely useful as a checklist — it covers things ML folks often skip, like success metrics, human-in-the-loop fallback, cost estimation, and risks/uncertainties, not just model architecture. It explicitly tells you to adapt or drop sections instead of treating the template as gospel, which is the right framing for a template like this. The appendix of links to real design doc practices (Google, Amazon's 6-pager, HashiCorp's RFC format, Stitch Fix) is a solid collection of reference material beyond the template itself.
Despite the repo description promising 'examples', there are no filled-out example design docs in the repo — just the blank template and a list of external links. It's one README; there's no tooling, no linting for completeness, nothing to actually enforce or generate a doc from this. Last pushed in March 2023, so some of the linked external resources may have moved or gone stale. The ML-specific sections (problem framing, data, techniques) are a thin paragraph each — most of the real value here is the generic engineering-design-doc skeleton, not anything ML-specific.
We read the README, the directory tree and a key source file in October 2026. Nobody pays to be listed. How we judge →