The Philosophical Developer — Chapter 65: The Website That Checked Every Bold Word Against the Code

Rhema now has a front door: rhema.guide — a bilingual product site with fourteen tutorials per language, screenshots of the real app, and downloads that deep-link to GitHub Releases instead of mirroring binaries. It went live the same day the app’s release post did, and the design expert who reviewed it found a single accent mark that inverted a trust sentence: Πότε, “when”, where the sentence needed Ποτέ, “never”. One tonos. The site had been telling poets the opposite of what I meant, in the one sentence about whether their words are ever touched.

That is what this chapter is really about: documentation is code, and it fails like code unless you gate it like code.

The site, in one paragraph

Hugo on GitLab Pages, the same house skeleton as this blog — custom theme in the repo, no theme from the internet, CI image pinned. English at the root, Greek under /el/, with a language switcher that click-throughs both directions and hreflang alternates including x-default. No cookies, no third-party loads, no analytics; the security reviewer verified zero external requests and an SRI-pinned same-origin script. Nothing phones home, and the site says so in a privacy paragraph that was itself audited for accuracy against the app at the release tag.

Four experts, two rounds

Every phase of the site had to pass four isolated reviewers before shipping: security, publisher, design, UX. Same rotation as the app’s phases, different failure shapes.

Security passed with one SHOULD that only a bilingual site produces: the Greek /download/ page linked a Windows installer URL that missed “Setup-” in the filename — a 404 that only the EL page had. Publisher failed twice. The first round caught tutorial steps that described the app as I remembered it rather than as it is: a “remove from shelf” that the app calls Trash, a label casing mismatch, a first-run default I had changed in the app the same week and the docs had not followed. The second round caught a worse one: a macOS keyboard caveat that offered a workaround which does not exist — no menu entry, no setting. The fix was not a better workaround; it was an honest gap, stated as one.

Design passed with the accent-mark blocker. UX passed after a fix batch: the mobile menu had been a translucent overlay with tap targets under 44 pixels; the muted text failed AA contrast math (fixed to 4.97:1); the download page had buttons that lied about which architectures they covered.

The string gate

The rule the whole site hangs on: every bolded UI label in every tutorial was checked against the app’s locale files at the release tag — not against my memory of the UI. Fourteen languages of JSON, grepped for the exact string the site claims the button says.

It caught two in Greek: the site wrote Φωτεινό where el.json renders Φως for “Light”, and Γραφή ως where the app says Γράψτε ως (“Write as {name}”). Both small, both fatal to a poet following the tutorial with the Greek interface on — the word they were told to look for would never appear on their screen. The same gate re-runs on every content change; it is a script, not a promise.

The lesson generalizes past Hugo: a documented example is part of the spec. Extract the real strings from the artifact the user will actually see, and assert the docs against them.

Screenshots from a harness, not a photographer

Sixteen new captures, English and Greek, at native 1700x1100 — and none of them hand-taken. The pattern that works: bolt a shot() call onto a proven end-to-end suite that already drives the real Electron app, and let it paint the state before capturing. One command, site-shots.sh, with the window-manager float-and-resize dance inside it, and a mock OpenAI endpoint to drive the Reader’s Eye state so the AI tutorial shows a real pane, not an empty one.

Standalone screenshot scripts time out and race; I stopped writing them. And the captures are DOM-verified, not eyeballed: one review pass missed an outline block that a geometry probe confirmed painted at 442x78. Vision is a fallback, not a gate.

Counts rot

The tutorials index lede said “Six guides” while fourteen cards rendered below it — the hero had been updated and the index had not. An earlier round caught “Thirteen languages” when the tag carried fourteen. After any content change: grep the site for number words and re-verify each against the actual count. A stale count is a small lie, and a site made of small lies reads as an unmaintained one.

The honest bit

The gates parked findings too, and they stay parked in the open: dark tutorial thumbnails are low-contrast at card scale (a re-capture pass would fix it), and a ghost button’s border sits at ~1.3:1 against paper, though its label passes AAA. The site carries the alpha disclaimer in its own voice — updates can break things, keep your backups, the safety nets are in the tutorials for a reason. Saying it before someone finds out the other way is cheaper every time.

And the accent mark: Πότε became Ποτέ on both pages within the hour of being caught. The reviewer saw what I could not — after three days of looking at the sentence, my eye read what it should say, not what it did. A machine that never read this post would have caught it too, if it had been diffed against the locale file. That is the argument for the whole gate, in one tonos.

Sources

1. https://rhema.guide — the Rhema product site (EN+EL tutorials, downloads, alpha honesty)
2. https://github.com/dark5un/rhema — Rhema: word processor for books and poetry, public alpha
3. https://onlyascii.dev/posts/chapter-64-the-word-processor-that-learned-a-poem-is-not-a-paragraph/ — Chapter 64, the app’s launch post