Your setup doc is a checklist, not the running stack

Most teams have a "Local setup" page. Clone the repo, copy .env.example, start Postgres, run migrations, start the API, start Vite, start the queue worker. It lives in Notion, Confluence or a README, and it is accurate on the day someone writes it.

Then the queue moves to a different port. Someone adds a Stripe webhook listener. The page still lists five steps when there are seven, and the new hire finds out at 10am on their first day.

The page is not the problem. Asking one page to do two jobs is.

Two different kinds of knowledge

A setup page mixes two things that age at different speeds:

• Reasoning. Why Postgres comes before migrations. Why the worker needs Redis. Which env values are per developer and which are shared. This changes slowly and needs prose.
• State. Which processes are running right now, on which ports, and whether they are healthy. This changes every few minutes and should never be typed by hand.

Notion Elevation draws a similar line between checklists and frameworks. A checklist says what to do. A framework says what to decide, in what order, and why each step depends on the one before it. For dev setup, the "why" is worth writing down. The "what is running" should come from software.

What belongs in the doc

• The order things start in, and the reason for that order
• Which services are optional for which kind of work
• Where secrets come from, never the secrets themselves
• Who to ask when the order stops making sense

What belongs on the board

• The processes themselves, as a group that starts in order
• Ports, health and logs, read live instead of from memory
• The env keys that are missing, not the ones you assume are set
• Anything an agent needs to inspect before guessing

Once the board holds the state, the setup doc gets shorter and stays true longer. It can say "start the API group in Rig" and spend its words on why the group looks the way it does.

The test

Ask a new teammate to follow the doc on a clean Mac. Every time they have to ask "is it running?", that answer belongs on the board. Every time they ask "why does it need this?", the answer belongs in the doc.

https://userig.app/blog/setup-doc-is-a-checklist-not-the-stack