DEV Community

CrisisCore-Systems
CrisisCore-Systems

Posted on

Maintaining truthful docs over time: how to keep security claims honest

#documentation #security #softwareengineering #writing

Series: Start here · Part 1 · Part 2 · Part 3 · Part 4 · Part 5 · Part 6 · Part 7 · Part 8 · Part 9 · Part 10

This post is Part 10 in a Dev.to series grounded in the open-source Pain Tracker repo.

  • Not medical advice.
  • Not a compliance claim.
  • This is about preventing doc drift from turning into false security promises.

If you want privacy-first, offline health tech to exist without surveillance funding it: sponsor the build → https://paintracker.ca/sponsor

Doc drift is inevitable — unless you design against it

Every repo accumulates drift:

  • features change, docs don’t
  • defaults change, READMEs don’t
  • “temporary” flags become permanent
  • old screenshots live forever like fossils

In most projects, drift is annoying.

In privacy/security contexts, drift is worse than outdated.

It becomes misinformation.

So the goal isn’t “write perfect docs.”

The goal is simpler (and harder):

keep docs anchored to things you can verify

Because a doc that can’t be verified eventually turns into storytime.

The trick: write docs that point to proof

When you say “offline-first”, point to something concrete:

  • the service worker scripts
  • the offline storage layer
  • tests that verify offline behavior
  • the offline fallback page

When you say “validated inputs”, don’t just say it—show the boundary:

  • Zod schemas
  • parse/safeParse wrappers
  • tests that prove invalid inputs fail

When you say “quality gates exist”, point at commands:

  • npm run check
  • npm run security-full
  • npm run accessibility:scan

This is what Pain Tracker’s docs style leans into:

  • engineering docs under docs/engineering/
  • explicit indexes like docs/index/accessibility.md
  • runnable scripts in package.json

It’s not just “documentation.” It’s a map of where the truth lives.

Don’t write claims. Write “how to verify” sections.

This is a tiny habit that pays forever:

Instead of:

“Exports are local-only and user-triggered.”

Write:

“Exports use a Blob + <a download> click. See file X. Try it by doing Y.”

Instead of:

“Analytics is consent-gated.”

Write:

“Analytics is behind env flag A and consent toggle B. Confirm by disabling A and verifying the loader is never injected.”

Why? Because “how to verify” survives refactors better than marketing sentences.

Also: it forces you to face your own reality. If you can’t explain how to verify a claim… you probably shouldn’t make it.

Automate doc validation when you can (but don’t pretend it proves truth)

Pain Tracker includes:

  • npm run docs:validate

That doesn’t “prove the docs are correct.”

But it does catch the boring breakage that causes long-term rot:

  • missing references
  • broken links/paths
  • formatting assumptions
  • structure drift

The point is to make “keeping docs healthy” an explicit, repeatable action—not an afterthought somebody remembers at 2am.

Separate claims from guarantees (and never blur the line)

A good rule for security docs:

  • describe what the code does
  • avoid implying it solves threats it doesn’t

Examples of safe phrasing:

  • “Data stays local unless the user exports it” (if export is explicit)
  • “Analytics is gated behind an environment flag + consent” (if both gates exist)
  • “Encryption-at-rest protects against opportunistic access to the browser profile” (scoped)

Examples of risky phrasing:

  • “secure” (without scope)
  • “compliant” (without a legal program)
  • “protected from attackers” (without a threat model)
  • “HIPAA-ready” (just… no)

Truthful docs don’t undersell the work. They just refuse to cosplay certainty.

Make docs part of your routine, not a one-time event

The quiet killer is “docs as a launch artifact.”

You write them once, ship, and then the code evolves while the docs decay.

Pain Tracker ships scripts meant to keep Dev.to content consistent and synchronized:

  • npm run devto:dry-run
  • npm run devto:sync-content
  • npm run devto:sync-titles

Meta-lesson:

publishing should be a process, not a copy/paste moment

If you can’t re-run the publishing process, you can’t keep truth stable.

A simple system that works (even for small teams)

If you want something you’ll actually maintain, here’s a pragmatic pattern:

  • Every major claim gets a “Proof” link (code/tests/commands)
  • Every doc page gets a short “How to verify” section
  • Every release runs the same gate commands you tell readers to run
  • Every refactor PR that changes a boundary must update at least one doc link or test

It’s boring. It’s reliable. It keeps drift from turning into lies.

Wrap-up

If you only take one thing from this whole series:

Make your claims testable.

That’s how you earn trust without pretending to be perfect.

Prev: Part 9 — Quality gates that earn trust

Support this work

Top comments (0)