Tag: documentation
9 items with this tag.
A personal design system for scholarly output
Almost everything I produce starts as a markdown file and ends in a different format — a slide deck, a handout, a Word document, this website — and until September 2026 I designed each one from scratch. I've replaced that with a personal design system with one visual language, one identity, and a template for each format, all reading the same token file. This post explains what the system is, how the pieces fit together technically, and what's still unfinished.
YAML
YAML is a human-readable format for storing structured data as plain text. In knowledge management and publishing workflows, it appears most commonly as the frontmatter block at the top of markdown files, where it holds metadata — title, author, date, tags — that tools can read without parsing the document itself.
Distributed version control
Distributed version control tracks changes to files so that every contributor holds a complete copy of the project and its full history, with no central server to depend on. It allows offline work, parallel development, and recovery from any copy, and it lets partners who share a document, such as a practice assessment document, each keep the whole record of how it changed.
Git
Git is a distributed version control system that tracks changes to files over time. It records who changed what and when, allows you to move between earlier and later states of a project, and lets multiple people work on the same files without overwriting each other's contributions.
Seven principle for collaborating with AI
Seven principles for extended AI collaboration, distilled from a week-long project to restructure a large note collection using Claude Code. The principles cover goal-setting, understanding what AI can and cannot contribute, investing in planning conversations, adaptive planning, safety infrastructure, treating AI output as drafts, and expecting to learn something about your own thinking. Offered not as rules to follow but as patterns to recognise.
Building an AI-ready knowledge base
A detailed account of a week-long project to restructure 5,819 Obsidian notes using AI as a working partner. The project involved building a 23-category taxonomy, migrating thousands of legacy notes to a consistent metadata structure, and generating AI-written descriptions for every note in the collection. The piece describes not just what was done, but how extended planning conversations, external project documentation, and careful human review at each phase made the work tractable. The most unexpected outcome was that building infrastructure for a note collection required articulating, for the first time, precisely how I think about my academic field.
Documentation debt
The accumulated cost of outdated, ambiguous, or poorly structured institutional knowledge — long paid invisibly by readers who work around the gaps, and exposed when AI agents read the same documents literally.
Markdown
A way of writing formatted documents in plain text — a hash for a heading, asterisks for emphasis — so the source stays readable and converts to anything.
Building an AI workflow for academics with structured documentation
Most advice on building an AI workflow for academics concentrates on writing better prompts. After several weeks of restructuring years of scholarly output with Claude Code, I've found the leverage lies in the structured context around the model — documentation that works as external memory, a cycle of testing rules and locking in the ones that hold, and the discipline of making implicit connections explicit. The same applies to institutions, where AI tools are only as reliable as the information architecture they're given.