Laith Al Enooz
Résumé
← Logs

2 min read

Facts a machine can check shouldn't be typed by a person

  • documentation
  • architecture
  • mobility

FuratGo is six repositories — an API, an ops console, three Flutter apps and a shared Dart package — held together by a wiki. The first version of that wiki was written by hand, carefully, and it was good. One page stated the test count, the current branch and two commit SHAs.

Six days later every one of those facts was wrong, and the page looked exactly as authoritative as the day it was written.

Stale docs fail silently

That’s the real problem with documentation drift: it doesn’t announce itself. A broken build is loud. A wrong number in a README is quiet, confident and believed. The cost lands later, on whoever trusts it — often me, months on, with no memory of having typed it.

Split the wiki in two

The fix was to sort every fact by who can verify it:

  • Generated pages hold everything a script can read straight from the code — exactly the kind of fact that first page got wrong. A script regenerates them, so they’re correct by construction and never typed by a person.
  • Hand-written pages hold only what code cannot say: why a decision was made, and what breaks if you change it.

The rule is short: facts a machine can check should never be typed by a person. Everything left over for humans is judgment, which doesn’t go stale the same way.

Write the contracts on the seam

Most of the hand-written half turned out to be about the spaces between repos, because that’s where the silent failures live:

  • The geohash precision used for matching is implemented twice, in two languages, with no shared source of truth. Change one and matching quietly degrades.
  • The SOS payload arrives over REST and over the broadcast channel, and the two shapes disagree on field names. Nothing errors; the wrong field is simply empty.

Neither belongs inside either repository; each repo is internally correct. So they’re written down on the seam, in the wiki, where someone changing either side will find them.

The principle

Divide documentation by what can verify it. Generate what the code already knows, write by hand only what it can’t, and spend the human effort on the contracts between systems — the places where nobody’s tests are looking.