Skip to content

Writing criteria

Every guide in this series is written against the same nine criteria:

  1. Plain words, real ideas. If a term is technical, it is introduced and used with a clear meaning. No pretending something is simpler than it is, and no dressing something simple in jargon to make it sound deep.
  2. No hype. The tool being covered is never "revolutionary" or "game-changing." If it is good at something, the guide shows the thing it is good at. If it saves time, the guide says how much, or doesn't say.
  3. Honest about limits. What the tool does not do, where it is the wrong tool, and what it costs in real terms (setup time, concepts you must hold, performance). A guide that only praises is an advert, not a guide.
  4. No invented numbers. Speeds, sizes, and counts are measured, quoted from the tool's own documentation as such, or left out. Rules of thumb are labelled as rules of thumb.
  5. Checkable. Where the guide reports what the author ran, it says what was run and what came back, in enough detail that a reader can repeat it and get the same answer. Where a claim rests on documentation rather than a run, the guide says so.
  6. Respect the reader's setup. Readers have real machines with real constraints. The guide does not assume a fresh install, an empty disk, or admin rights the reader may not have, without saying that it is assuming them.
  7. Safety isn't skipped. Commands that can delete, overwrite, or expose data are flagged where they appear, not in a disclaimer at the end. Defaults that are dangerous are named as dangerous.
  8. Scoped. The guide covers its tool and stops. It does not wander into comparisons it hasn't verified, or advice about tools it isn't about.
  9. Structure over prose. Short sections, a clear order, and headings that tell the truth about what follows. A reader in a hurry can skim; a reader in trouble can land on the one section they need.

Verification notes

  • Syncthing is a real, widely used program and the version used here throughout is v1.27.2-ds4 ("Gold Grasshopper", go1.22.2, linux-amd64), the standard Linux build as packaged by the distribution: the lab downloaded the distribution package (syncthing_1.27.2~ds4-1ubuntu0.24.04.3) from the archive and extracted the binary into the lab directory — it was never installed system-wide, and the version line is from the binary's own --version output, captured in the lab transcripts. Behaviour that is version-shaped is claimed for this version, as captured; where the text generalises, it says so or cites the official documentation.
  • The lab (syncthing-lab/: a rerunnable harness script, run-lab.sh, two small helpers, and twelve numbered transcripts) ran exactly what the chapters claim: two complete Syncthing instances on one machine, separate configuration homes, loopback addresses only (GUI/API on 127.0.0.1:8385 and 127.0.0.1:8395, sync listeners on 127.0.0.1:22005 and 127.0.0.1:22006, fixed peer addresses), sharing two folders as the two fictional newsletter volunteers "willow" and "juniper", with global and local discovery, relays, and NAT traversal switched off (and the switches read back through the API in chapter 9), usage reporting declined, and automatic upgrades disabled. Sync was proven by sha256sum matches and by the API's own status counts, never by progress displays. Both instances were shut down through the API at the end; a final process check shows none running.
  • Verified by running, chapter by chapter: identity generation (config, certificate, key, generated device ID and API key, the default folder and outreach defaults a fresh config carries, and the lab's quietened settings read back from the file), pairing by device ID through the API and the resulting TLS 1.3 connection report, the unauthenticated API answer (HTTP 403), folder creation from Syncthing's own template, first sync of four files into a subfolder with matching hashes and the .stfolder marker, an edit propagating with matching hashes, a delete propagating to both sides with no surviving copy while versioning was off, .stignore not syncing while the included .stglobalignore did, both devices' ignore patterns holding files home in both directions with a control file syncing, trash-can versioning being enabled live through the API, an overwrite archiving the replaced generation on the receiving device under its original name, a second overwrite replacing that archived copy in turn, local edits on the originating device producing no archive there, a delete being archived on the receiving device, recovery by copying the archived file back with hashes matching the pristine fixture on both devices, a genuine conflict produced by editing both sides while disconnected (newer edit winning the name on both devices, the older kept whole as a .sync-conflict file that itself synced), a send-only folder refusing a reader's file entirely (status counts unchanged), a receive-only folder's local edit never leaving the device with the divergence visible in its own status bytes, revert discarding the local edit and restoring identical hashes (and, in the lab's final inventory, the receive-only device's local addition file as well), the API surface used throughout including status, connections, folder status, ignore lines, options readback, the built-in syncthing cli reading the same API, pause holding a new file back and resume delivering it, and API shutdown of both instances. The web GUI was verified to exist and answer on the same address (HTTP 200, text/html); no GUI workflow was driven, and no chapter claims one.
  • Capture hygiene, declared: the transcripts are the harness's record. Lines beginning $ are the command as run; [exit N] and [HTTP NNN] markers are the harness reporting the command's exit status or the HTTP status of the REST call above it; lines beginning $ # are harness narration (a wait for a sync condition, or a fixture step performed between commands) and never program output; REST transcript lines display the API key as $KEY while the calls themselves carried the lab's real, throwaway keys. Chapter quotations elide with … where a listing runs long, and show JSON through the jq filters printed in the transcripts. Instance log files were used for diagnosis only and are not quoted.
  • Where the guide states behaviour it did not run, it attributes it to Syncthing's official documentation at the sentence: the conflict tie-break by device ID when modification times are equal, and the rule that an edit beats a delete (the edited file is resurrected, with no conflict copy). Everything else behavioural was observed in the captures above.
  • Documented-only (not run in this sandbox): global discovery over the internet and finding a device by ID alone; relay servers carrying traffic; NAT traversal and router port mapping; local (LAN) discovery, including multicast quirks; all three running over real networks between real machines (the lab is loopback-only by design, so latency, firewalls, and sleeping laptops are out of scope); introducers and auto-accepting folders (their settings are shown in the pairing object, set to false, and not exercised); the web GUI beyond answering an HTTP request, and the Android, desktop, and other platform apps' interfaces; the simple, staggered, and external versioning schemes (staggered is described in one sentence from the documentation where the trash can's single- generation behaviour is reported); receive- encrypted folders and untrusted devices; upgrading Syncthing itself (disabled in the lab); installing it as a system service; syncing file permissions, ownership, symlinks, and case-only renames (the folder template's ignorePerms default is reported, the rest untouched); folders shared between more than two devices; and large-file or large-folder performance, about which the guide makes no claims at all.
  • Fixture note (series rule): the newsletter, its volunteers, its devices, and every file in examples/ are invented for this guide and belong to no real organisation. The usual dull checks were run: the fixture set contains no real person, place, or event, and the example byte counts quoted are the captures' own.
  • Safety notes: the private key file (key.pem) is called out as the device itself when it appears, and the API key's role as a password is stated in chapter 2 rather than assumed. The two destructive behaviours this tool has by design — a delete propagating with no recycle bin (chapter 4) and revert discarding a receive-only device's additions as well as its edits (chapter 8) — are presented as headline findings in their chapters, not footnotes, and the guide states plainly that Syncthing is a mirror, not a backup, and names real backups as the reader's own responsibility. Every example runs between the reader's own devices or the lab's two instances; the guide gives no command for reaching anybody else's machine, and pairing itself is shown as a mutual, deliberate act.