How guides are made and checked

Spatial Workflow has 1,421 guides to doing GIS work in Python. Each one answers one question — a concept, a task, or an error — and each one is held to the same promise: the code runs as written, on the real data the page names, and every number the page quotes came out of that run. This page explains how that is done, and where it is not perfect.

Drafting: an AI model writes the first version

Guides are drafted with an AI model (Anthropic's Claude). We say so plainly because a reader deciding how far to trust a page deserves to know. The draft is where the work starts, not where it ends: nothing in it is taken on trust. The code is run, the numbers are replaced with what the run printed, the prose is rewritten to match what the run actually showed, and a person decides what is published.

Running: every code block, in order, on named open data

Each guide's Python is run top to bottom in a fresh folder, the way a notebook would run it. The first block fetches or builds every input the page uses — from sources such as OpenStreetMap, national statistics offices, the Food Standards Agency, Natural Earth and NASA — and the The data used on this page section names each one. The output shown under each code block is pasted from that run, never typed. A separate check lists any number in the prose that no output printed; each one is traced to a run or rewritten. The rare snippet with placeholder paths, such as a quick answer that reads /data/dem.tif, is marked as a fragment and is not run.

Each guide carries a note showing when its code was last re-run and with which versions of Python and the libraries. All 1,421 guides have been reproduced this way. Every guide can also be downloaded as a Jupyter notebook, so you can run it yourself.

Checking: one question per page

Before a guide is written, its question is compared with every existing guide — by wording and by meaning — and a question the site already answers is not written twice. After a build, every guide is compared again: on search intent, on overlapping prose, on shared results and on meaning. A page that mostly restates other pages fails the build until it is cut back to what it alone says, merged into the page it repeats, or shown to answer a genuinely different question.

Figures: drawn from the data, not decorated

Diagrams are generated from written specifications, so a number on a chart is the number in the run. Maps are rendered with QGIS from the same open data, by re-running the guide's own code; if the source has changed and the numbers no longer agree with the text, the map is not drawn.

Keeping guides true

Libraries change, and data sources move or update. Guides are re-run oldest first, starting with those whose recorded library versions differ most from current releases, and every data source the guides download is checked regularly for links that have broken or moved. When a re-run prints something new — a register that now lists 1,365 businesses instead of 1,366 — the page follows the new run: outputs, prose and figures. Substantive changes are listed under the guide as Changes, with a date.

When something is wrong

If a guide does not run, quotes a number you cannot reproduce, or links to data that has gone, please tell us: the contact page says what to include. Corrections are the most useful mail we get.