Skip to content

Writing Criteria

Standards every guide in this collection is written and checked against. They exist because the audience is working IT people who will follow the instructions on real systems, and because AI-assisted writing has known failure modes — confident invention, vague hand-waving, and numbers from nowhere — that a checklist can actually catch.

The standard

  1. Plain words first. Define every term the first time it appears, in ordinary language. Jargon is allowed after it has been earned, never before. If a sentence needs a specialist dictionary, rewrite the sentence.

  2. No hype. No "blazing fast", no "revolutionary", no exclamation marks doing the work of evidence. State what the thing does and let the reader decide whether to be impressed.

  3. Honest about limits. Every guide names what the tool is bad at, what it does not do, and who should use something else. A guide that reads like a sales page has failed even if every fact in it is true.

  4. No invented numbers. Performance figures, prices, dates and limits come from the project's documentation or from measurements actually taken — never from memory, vibes, or a language model's sense of what sounds right. Where a number is given, its source is a document the reader can check or a command in the verification notes.

  5. Checkable. Commands are given exactly, and the expected result is stated, so a reader who gets something different knows immediately that they have diverged. Claims about behaviour are tied to transcripts where a lab ran.

  6. Respect the reader's setup. The reader's machine is theirs. No destructive commands without warning, no "just disable the firewall", no assumptions that the reader can break production to follow along. Lab work happens in a lab.

  7. Safety is not skipped. Where a feature is dangerous when misunderstood (public access, authentication, restoring over live data), the guide says so at the point of use, not in a footnote.

  8. Scoped. Each guide covers its subject at the depth a competent reader needs to run the thing well. It does not try to replace the official documentation, and it says where the official documentation takes over.

  9. Structure over prose. Numbered chapters in a deliberate order, tables where a comparison is the point, a glossary that defines terms once, worked examples with names the reader can reuse.

Verification notes

A guide's claims are only as good as what was actually done. This section records, for this guide, what ran, what was read, and what is documentation-only — so the reader can weigh every claim.

  • Version verified against: Traefik v3.7.16 (codename langres), the current release on the day of the build, run as the project's official static binary on Ubuntu 24.04. The download was checked against the project's published checksums file (sha256sum: OK) before the binary was executed, exactly as chapter 3 instructs the reader to do.
  • Primary sources read: Traefik's official documentation (concepts, static and dynamic configuration, the file and Docker providers, routing, middlewares, TLS and ACME, the API), the v3.7.16 release notes and checksums, and the binary's own reported version and API output.
  • Ran for real (transcripts in traefik-lab/transcripts/):
  • Download, checksum and version (t00) and the ping endpoint.
  • Host-based routing between two local backends, including Traefik's own 404 for an unclaimed name and for the bare proxy address (t01).
  • PathPrefix routing — one host served by two backends, split by path — and the default priority behaviour, applied by file watch with no restart (t02).
  • The API (/api/version, routers, overview) and dashboard answering 200, in the deliberately insecure lab mode the guide warns about (t03).
  • Middleware against live backends: stripPrefix rewriting the path the backend received; a custom request header observed by the backend; basicAuth refusing requests without and with the wrong password (401) and passing the right one (t04).
  • Round-robin load balancing across two servers of one service; an active health check retiring a killed server from rotation and restoring it when it returned — both directions observed in real traffic, not inferred (t05).
  • TLS with a local certificate authority created for the lab: the certificate served, a CA-trusting client admitted, an untrusting client refused (curl exit 60), and a redirectScheme middleware sending HTTP to HTTPS with the correct Location (t06).
  • Dynamic reload: a new site added by writing one file into the watched directory, answering within seconds, Traefik's process ID identical before and after (t07).
  • Errors hit and diagnosed: The sandbox's HTTP proxy intercepted the lab's .test names until bypassed — a test-harness fault, kept out of the chapters except as lab-notes honesty. A deliberately broken dynamic file produced Traefik's real rule-parse error in the log while the last good configuration kept serving; that genuine failure is chapter 15's and t07's specimen, not a reconstruction. One reload was observed to land just after a test request raced it, which is why the notes describe reload latency honestly (about two seconds) rather than "instant".
  • Documented only (labelled wherever it appears): the Docker provider and label-based configuration (chapter 9) — the build sandbox has no Docker, so nothing in that chapter was executed; Let's Encrypt / ACME issuance (chapter 7's second half) — a public domain and an internet-reachable server are prerequisites a sandbox does not meet; Kubernetes providers, TCP and UDP routing, and metrics exporters, which were not exercised at all. The platform chapters (neighbours, limits) are judgement based on vendor documentation, not benchmarks.
  • Fixtures: Every name, host and credential in this guide is invented for general audiences: the sites fern.test, otter.test and heron.test (in the reserved .test domain, so they can never collide with real sites), the backends fern, otter and fern-two, and the basicAuth user "warden" with the lab-only password "lantern42", published openly as a reproducibility fixture that protects nothing and must protect nothing of the reader's.

Standards checklist (self-assessed)

  • [x] Plain words first: every term defined at first use; glossary chapter.
  • [x] No hype: no superlatives used as evidence anywhere.
  • [x] Honest about limits: limits chapter and the dashboard's insecure mode called out at the point of use.
  • [x] No invented numbers: versions from the binary's own output; reload timing stated as observed; no performance figures claimed at all.
  • [x] Checkable: each lab chapter names its transcript and the expected result, including failure results (401, 404, exit 60).
  • [x] Respect the reader's setup: lab on reserved names and high ports; public-port and root-capability implications stated in chapter 3.
  • [x] Safety not skipped: basicAuth over HTTP warned about in chapter 6; certificate-authority key custody in chapter 7; the dashboard in chapter 8; publication posture in chapter 14.
  • [x] Scoped: Kubernetes and TCP/UDP acknowledged and left to official documentation.
  • [x] Structure over prose: numbered chapters, comparison tables, glossary.