diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 7a074f12de..043ac7a9c7 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -37,12 +37,4 @@ We've released a [Model Port guide](https://blog.comma.ai/openpilot-port-guide-f
 
 If you port openpilot to a substantially new car brand, see this more generic [Brand Port guide](https://blog.comma.ai/how-to-write-a-car-port-for-openpilot/).
 
-## Testing
 
-### Automated Testing
-
-All PRs and commits are automatically checked by GitHub Actions. Check out `.github/workflows/` for what GitHub Actions runs. Any new tests should be added to GitHub Actions.
-
-### Code Style and Linting
-
-Code is automatically checked for style by GitHub Actions as part of the automated tests. You can also run these tests yourself by running `pre-commit run --all`.
diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md
new file mode 100644
index 0000000000..485adaf1de
--- /dev/null
+++ b/docs/WORKFLOW.md
@@ -0,0 +1,42 @@
+# openpilot development workflow
+
+Aside from the ML models, most tools used for openpilot development are in this repo.
+
+Most development happens on normal Ubuntu workstations, and not in cars or directly on comma devices.
+
+## Quick start
+
+```bash
+# get the latest stuff
+git pull
+git submodule update --init --recursive
+
+# update dependencies
+tools/ubuntu_setup.sh
+
+# build everything
+scons -j$(nproc)
+
+# build just the ui with either of these
+scons -j8 selfdrive/ui/
+cd selfdrive/ui/ && scons -u -j8
+
+# test everything
+pytest .
+
+# test just logging services
+cd system/loggerd && pytest .
+
+# run the linter
+pre-commit run --all
+```
+
+## Testing
+
+### Automated Testing
+
+All PRs and commits are automatically checked by GitHub Actions. Check out `.github/workflows/` for what GitHub Actions runs. Any new tests should be added to GitHub Actions.
+
+### Code Style and Linting
+
+Code is automatically checked for style by GitHub Actions as part of the automated tests. You can also run these tests yourself by running `pre-commit run --all`.