Structure Beats Magic ← All writing

Structure Beats Magic

Help Is a Document in the Vault

The help text of every screen and 83 pages of my family portal are notes in the vault. The portal gets them back byte for byte.

By Jaco van der Laan · 2026-10-17
Help Is a Document in the Vault

Two sets of help

I had two places where my system explained itself. The Control Plane has a question-mark button on every screen with a description of that screen. And the family portal, a small site on the NAS that my family and I read when something in the house or the network needs explaining, has 83 pages in Dutch and English: the cameras, the backups, how the NAS is wired. The portal pages were 166 files in a folder outside the vault, in a block markup of their own (a ::table here, a ::note there).

Two sources meant two places to edit, and one of them was invisible to everything the vault does: search, links, properties, history.

One kind of document

Help became a note type. A screen description is a note with kind: screen-help, saved in a folder named after the screen, with its images and PDFs beside it. A portal page is a note with share: family-portal, in the area it belongs to: the house pages with the house, the travel pages with travel.

The portal still needs its own files, so a script exports every note flagged family-portal back to the portal's folder. It removes the properties the vault added and writes what the portal always had. The check compares the result with a backup of the original files, and zero differ. The nightly export reports how many files it wrote. A non-zero number would mean someone edited a note and the portal had not caught up. Today it wrote none of the 166.

The part that went wrong

The screen-help notes and the portal pages ended up in the same folder for the system area. The Screens tab listed everything in that folder as a screen: 250 screens where there were 202, because 48 of them were portal pages. The Screens tab now lists a note only if its kind is screen help. A folder says where a note is saved, and the kind says what it is.

Structure + Data + AI + Rules + Skills → Systems

← More writing Work with Jaco →