Where docs live matters:
README.md — front door: what + quickstart.docs/ — long-form: architecture, ADRs (architecture decision records), guides.CHANGELOG.md — version history. Auto-generated from conventional commits is fine.- Inline JSDoc / docstrings — for APIs other code calls.
- Code comments — only when why isn't obvious from the code (a workaround, an invariant, a deliberate choice).
ADRs are the high-leverage habit:
docs/adr/
0001-use-postgres.md
0002-tailwind-over-css-modules.md
0003-isomorphic-git-for-engine.md
Each ADR captures: context, decision, consequences, alternatives considered. Future you (or new hires) instantly understand "why are we doing it this way".
Don't write docs that duplicate the code. Write docs that capture decisions the code can't show you.