diff --git a/README.md b/README.md
index 5e2f51d7..429e5c79 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,13 @@
 
 [![Check config](https://github.com/python/buildmaster-config/actions/workflows/check.yml/badge.svg)](https://github.com/python/buildmaster-config/actions/workflows/check.yml)
 
+> [!NOTE]
+> This README has instructions for Buildbot administrators.
+> User guides are in the Devguide:
+> - [Working with buildbots](https://devguide.python.org/testing/buildbots/)
+> - [New buildbot workers](https://devguide.python.org/testing/new-buildbot-worker/)
+
+
 ## Private settings
 
 The production server uses /etc/buildbot/settings.yaml configuration file which
@@ -47,15 +54,35 @@ a `*/15` cron interval using the `update-master` target in `Makefile`.
 
 ## Add a worker
 
-The list of workers is stored in `/etc/buildbot/settings.yaml` on the server.
-A worker password should be made of 14 characters (a-z, A-Z, 0-9 and special
-characters), for example using KeePassX.
+To add a worker, people follow the [Devguide](https://devguide.python.org/testing/new-buildbot-worker/)
+which directs them to an issue template to fill out.
+Make sure you have all the info the template asks for.
+
+If the owner did not request a new password (that is, they're reusing one
+from an existing worker):
+
+* Make a PR (or ask the new owner to make a PR) that adds the worker to
+  `master/custom/workers.py`, with the owner username as first component.
+* Check `/etc/buildbot/settings.yaml` on the server: the email and GitHub
+  username should match.
+* Merge the PR.
+* Watch the logs; wait for Salt to pull the PR and restart the server.
+* Close the issue. You're done.
+
+When adding a new owner, or a new worker password for an existing owner,
+do the following first:
+
+* Generate a password using e.g.:
+
+      import secrets
+      print(secrets.token_urlsafe(14))
 
-* Generate a password
-* Add the password in `/etc/buildbot/settings.yaml`
-* Restart the buildbot server: `make restart-master`
+* Check the username doesn't already exist in `/etc/buildbot/settings.yaml`.
+* Add an owner entry to `/etc/buildbot/settings.yaml`.
+* Check the config using `make check` (on the server).
+* E-mail the password to the new owner.
+* As above: add the worker to `master/custom/workers.py`; merge; restart.
 
-Documentation: http://docs.buildbot.net/current/manual/configuration/workers.html#defining-workers
 
 ## Testing changes locally
 
diff --git a/master/custom/workers.py b/master/custom/workers.py
index c0d95ff4..9d41bfa6 100644
--- a/master/custom/workers.py
+++ b/master/custom/workers.py
@@ -10,6 +10,10 @@
 
 from custom.worker_downtime import no_builds_between
 
+# List of workers.
+# See also: Buildbot worker documentation, http://docs.buildbot.net/current/manual/configuration/workers.html#defining-workers
+
+
 
 # By default, the buildmaster sends a simple, non-blocking message to each
 # worker every hour. These keepalives ensure that traffic is flowing over the