diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3adfc15
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,35 @@
+# Contributing guide
+
+Things you'll need:
+
+- To create [Pull Requests](https://forgejo.org/docs/latest/user/pull-requests-and-git-flow/), you will need to register your [pub.solar ID](https://auth.pub.solar) first.
+- For small changes, e.g. to documentation, you can directly edit files in the browser.
+
+### Getting a development shell
+
+First, get a local copy of this repository:
+
+```
+git clone https://git.pub.solar/pub-solar/infra.git
+cd infra
+```
+
+then, install [the package manager nix](https://nixos.org/download).
+
+Finally, run:
+
+```
+nix develop
+```
+
+This will install a development shell (devshell) with all required tools.
+
+### Final checks before creating a Pull Request
+
+Before creating a pull request, it's recommended to check the formatting:
+
+```
+treefmt
+```
+
+If you are a terminal-lover, the [AGit alternative](https://forgejo.org/docs/latest/user/agit-support/) to the web based Pull Request workflow might be interesting.
diff --git a/README.md b/README.md
index 189bf3b..147936d 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,6 @@ The architecture we are working towards is a vast simplification of what it was
 
 ## Contributing
 
-If you'd like to contribute, it makes sense to talk to the crew on Matrix via [#hakken](https://matrix.to/#/#hakken:pub.solar?via=chat.pub.solar). We can help figuring out how things work and can make sure your ideas fit the pub.solar philosophy. Of course [popping a pull request](https://docs.gitea.com/next/usage/pull-request#creating-a-pull-request) is always celebrated.
+If you'd like to contribute, it makes sense to talk to the crew on Matrix via [#hakken](https://matrix.to/#/#hakken:pub.solar?via=chat.pub.solar). We can help figuring out how things work and can make sure your ideas fit the pub.solar philosophy. Of course [popping a pull request](https://forgejo.org/docs/latest/user/pull-requests-and-git-flow/) is always celebrated.
 
-To start, see [how to get a development shell](./docs/development-shell.md).
+To start, check our [contributing guide](./CONTRIBUTING.md).
diff --git a/docs/development-shell.md b/docs/development-shell.md
deleted file mode 100644
index 2b7d6c6..0000000
--- a/docs/development-shell.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Getting a development shell
-
-Clone this repository:
-
-```
-git clone https://git.pub.solar/pub-solar/infra.git
-cd infra
-```
-
-then, install [the package manager nix](https://nixos.org/download).
-
-Finally, run:
-
-```
-nix develop
-```
-
-This will install a development shell (devshell) with all required tools.