diff --git a/docs/maintainers/handbook.md b/docs/maintainers/handbook.md
index d3c1d73..ebccbe3 100644
--- a/docs/maintainers/handbook.md
+++ b/docs/maintainers/handbook.md
@@ -696,6 +696,21 @@ You should be able to deploy this overriden configuration now.
 
 ## Linting rules
 
+### R015: "long secret names"
+
+Due to limitations placed by the Docker runtime, secret names must be < 64
+characters long. Due to convetions in recipe configuration and how `abra`
+works, several characters are appended to secret names during a deployment.
+This means if you have a domain `example.org` and a secret `foo_pass`, you'll
+end up with something like `example_org_foo_pass_v1` being used for the secret
+name.
+
+Based on a discussion in
+[`#463`](https://git.coopcloud.tech/coop-cloud/organising/issues/463) and
+looking on what is implemented currently in existing recipes, we came up with a
+general rule of thumb that secret names in recipe configurations should be < 12
+characters long to avoid errors on deployment.
+
 ### R014: "invalid lightweight tag"
 
 This is an issue related to the way Git/`go-git` handle Git tags internally. We