CrisisCore-Systems

Posted on Feb 26 • Edited on Mar 3 • Originally published at dev.to

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

#documentation #security #softwareengineering #writing

If you want the fastest route through this catalog, start here and then come back to this post for detail.

Start Here reading path

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.