The CraftSyntax Manifesto
Little languages for real craft.
Humans use domain-specific languages every day. “Skinny caramel latte” works because customer and barista share the context. A useful computer language can capture the same working knowledge.
CraftSyntax explores the living vocabulary of a craft: its words, distinctions, defaults and habits. A good domain language should sound as if it belongs to its users.
01 / Principle
Begin with the working language.
The first duty of a domain language is to listen. It should begin not with the implementer’s convenience, but with the language that writers, artists, engineers, designers, and other practitioners already use.
02 / Principle
Name real distinctions.
A language names things well when it preserves distinctions that matter in practice: page and panel, location and action, asset and threat, component and connection.
03 / Principle
Keep the source readable.
Source should remain close to the shape of thought. It should be possible to read a document with pleasure, and to understand its intent without deciphering machinery.
04 / Principle
Hide the machinery.
TeX, parsers, databases, and generators are tools, not the subject. The mechanisms underneath should support the language, not dominate it.
05 / Principle
Use defaults intelligently.
A small language becomes humane when it makes sensible assumptions, so that a little input can produce a useful result.
06 / Principle
Permit refinement without clutter.
A language should be brief in the common case and more exact only when the work requires it.
07 / Principle
Make structure meaningful.
Structure is valuable not because it is formal, but because meaning can be checked, compared, transformed, and reused.
08 / Principle
Let tools catch inconsistency.
A compiler should notice broken references, missing states, and impossible combinations early, before they become expensive mistakes.
09 / Principle
Allow draft and strict ways of working.
Early work should tolerate incompleteness. Finished work should insist on coherence.
10 / Principle
Generate more than one view.
One source should be able to yield many useful forms: prose, diagrams, tables, cards, webpages, PDFs, or reports.
11 / Principle
Respect the craft.
A domain language should make its craft more visible, not reduce it to bureaucracy. The purpose is to assist judgement, not replace it.
12 / Principle
Build small languages carefully.
A little language is a piece of intellectual carpentry: modest in scale, precise in joinery, and best judged by how naturally it fits the work.