Notes

Short pieces on how software actually goes, written for developers in training courses and kept afterwards. None of this is course material. It is the part that stays true when the framework, the language and the course all change.

Nothing here needs reading in order and nothing depends on anything else.

Sidebars

Short decision aids. Each one is about a choice you are already making, whether or not you noticed making it. They exist because a course has to assume things, and what it assumes is never the same as what any particular person walked in with.

They are deliberately not exhaustive. Seven sections, two pages, and a few prompts for going further than two pages allow.

Venues

A venue file describes only where a codebase differs from what you would assume. Not documentation, not a rulebook — the diff.

The idea is small and it does more than it looks like it should: it gives a newcomer twenty minutes instead of two days, it gives an assistant the context that stops it suggesting the generally-right and locally-wrong thing, and — because it describes what is rather than what was decided — it can be checked, and therefore it can be wrong, which is the only reason to trust one.

What a venue file is, and what goes in it

Failure modes

A diagnostic catalog. Where code smells are aesthetic patterns to clean up, these are predictions about what goes wrong, keyed to what kind of work you are doing.

Every entry carries a when this isn’t a failure mode section, and that section is doing the real work — without it a catalog becomes a set of prescriptions, which is the exact problem it was written against.

These are practitioner notes rather than teaching material. They are longer, denser, and assume you have been on a project that went wrong.

About

Written by Jeff Gonzalez, with Claude. Sources live in the repository these are rendered from, so anything here can be wrong in a way that is checkable — which is the standard the notes themselves argue for.