The most valuable documentation is the kind you write while building — not after. My projects carry three files that have repeatedly saved me: DEPLOY.md, DESIGN.md, and SECURITY.md. Here is what each one is for and why they pay for themselves.

DEPLOY.md — the "how do I run this" answer

A step-by-step that a future you (or a teammate) can follow to deploy, update, and roll back — without asking you. It should include:

  • The exact build and deploy commands
  • Where configuration lives and what each setting does
  • How to back up and restore the data
  • The rollback procedure

The test of a good DEPLOY.md: can someone follow it on a fresh machine and get a working service, without Slack? If not, it is incomplete.

DESIGN.md — the "why is it like this" answer

Code tells you what; design docs tell you why. The decisions that matter are the ones where you chose between two reasonable options:

  • Why SQLite over Postgres (for now)
  • Why a single binary over a service split
  • Why this data model and not another

Six months later, that rationale is gold — it stops well-meaning "improvements" that reverse a decision you made for reasons nobody remembers.

SECURITY.md — the "what is the threat model" answer

What are you defending, and against what? Where do secrets live? How are sessions and permissions handled? What was reviewed and fixed? A short security doc turns "we should be careful" into a concrete, auditable list.

The rule that keeps them honest

Documentation rots. The fix is to treat these files as living parts of the build — update them in the same commit as the change they describe. A stale doc is worse than none, because it is confidently wrong.

Writing these three files costs an afternoon and saves a week of "how does this work again?" every time you return to the project.