diff --git a/maintainers/README.md b/maintainers/README.md
index 6c07b51a93bb8..83e9e50a23f64 100644
--- a/maintainers/README.md
+++ b/maintainers/README.md
@@ -119,8 +119,9 @@ When adding users to [`maintainer-list.nix`](./maintainer-list.nix), the followi
 
   Note: GitHub's "Verified" label does not display the user's full key fingerprint, and should not be used for validating the key matches.
 
-- Ensure that the user has specified a `github` account name and a `githubId` and verify the two match.
+- If the user has specified a `github` account name, ensure they have also specified a `githubId` and verify the two match.
 
+  Maintainer entries that include a `github` field must also include their `githubId`.
   People can and do change their GitHub name frequently, and the ID is used as the official and stable identity of the maintainer.
 
   Given a maintainer entry like this:
@@ -138,7 +139,7 @@ When adding users to [`maintainer-list.nix`](./maintainer-list.nix), the followi
 
   First, make sure that the listed GitHub handle matches the author of the commit.
 
-  Then, visit the URL `https://api.github.com/user/10137` and validate that the `login` field matches the provided `github` handle.
+  Then, visit the URL `https://api.github.com/users/ghost` and validate that the `id` field matches the provided `githubId`.
 
 ### Maintainer teams
 
diff --git a/maintainers/maintainer-list.nix b/maintainers/maintainer-list.nix
index 378975883d7d0..96e3ecf24ac6a 100644
--- a/maintainers/maintainer-list.nix
+++ b/maintainers/maintainer-list.nix
@@ -4,12 +4,13 @@
    handle = {
      # Required
      name = "Your name";
-     github = "GithubUsername";
-     githubId = your-github-id;
 
-     # Optional
+     # Optional, but at least one of email, matrix or githubId must be given
      email = "address@example.org";
      matrix = "@user:example.org";
+     github = "GithubUsername";
+     githubId = your-github-id;
+
      keys = [{
        fingerprint = "AAAA BBBB CCCC DDDD EEEE  FFFF 0000 1111 2222 3333";
      }];
@@ -20,16 +21,16 @@
 
    - `handle` is the handle you are going to use in nixpkgs expressions,
    - `name` is a name that people would know and recognize you by,
-   - `github` is your GitHub handle (as it appears in the URL of your profile page, `https://github.com/<userhandle>`),
-   - `githubId` is your GitHub user ID, which can be found at `https://api.github.com/users/<userhandle>`,
    - `email` is your maintainer email address,
    - `matrix` is your Matrix user ID,
+   - `github` is your GitHub handle (as it appears in the URL of your profile page, `https://github.com/<userhandle>`),
+   - `githubId` is your GitHub user ID, which can be found at `https://api.github.com/users/<userhandle>`,
    - `keys` is a list of your PGP/GPG key fingerprints.
 
-   Specifying a GitHub account is required, because:
-   - you will get invited to the @NixOS/nixpkgs-maintainers team;
-   - once you are part of the @NixOS org, you can be requested for review;
-   - once you can be requested for review, CI will request you review pull requests that modify a package for which you are a maintainer.
+   Specifying a GitHub account ensures that you automatically:
+   - get invited to the @NixOS/nixpkgs-maintainers team ;
+   - once you are part of the @NixOS org, OfBorg will request you review
+     pull requests that modify a package for which you are a maintainer.
 
    `handle == github` is strongly preferred whenever `github` is an acceptable attribute name and is short and convenient.