diff --git a/third_party/go/README.md b/third_party/go/README.md
index 7bcccca..05737ec 100644
--- a/third_party/go/README.md
+++ b/third_party/go/README.md
@@ -1,6 +1,44 @@
 Go dependency managment
 =======================
 
-Status: managed by fietsje
+Status: managed by [Gazelle](https://github.com/bazelbuild/bazel-gazelle).
 
-See //build/fietsje/README.md to learn how to change/add Go dependencies to monogon.
+
+    .--------.
+    | go.mod |------------.
+    '--------'            |
+        | go mod tidy     | bazel //:gazelle-update-repos
+        V                 |
+    .--------.            |
+    | go.sum |-----------.|
+    '--------'            |
+                          V
+    .---------------------------------.
+    | third_party/go/repositories.bzl |
+    '---------------------------------'
+                          | bazel run //:gazelle
+                          V
+                   .----------------.
+                   | **/BUILD.bazel |.
+                   '----------------'|
+                    '----------------'
+                          | bazel build //...
+                          V
+                   .-----------------.
+                   | build artifacts |
+                   '-----------------'
+
+Updating and adding new dependencies
+------------------------------------
+
+Add a Go dependency to your code, then:
+
+    $ go mod tidy
+    $ bazel run //:gazelle-update-repos
+
+NOTE: currently the first part (`go mod tidy`) doesn't work without performing some in-place symlinking in the repository. TODO(lorenz): document this
+
+Regenerating BUILDfiles
+-----------------------
+
+    $ bazel run //:gazelle