diff --git a/nixos/modules/misc/ids.nix b/nixos/modules/misc/ids.nix
index ab3568c4d992..814ee77c0119 100644
--- a/nixos/modules/misc/ids.nix
+++ b/nixos/modules/misc/ids.nix
@@ -356,7 +356,24 @@ in
       localtimed = 325;
       automatic-timezoned = 326;
 
-      # When adding a uid, make sure it doesn't match an existing gid. And don't use uids above 399!
+      # When adding a uid, make sure it doesn't match an existing gid.
+      #
+      # !!! Don't use uids above "399"! !!!
+      #
+      # The reason behind this restriction is that, NixOS by default allocates
+      # system user UIDs/GIDs in the range of `400..999`. System users/groups
+      # created using command like `useradd` will have UID and GID in this range[1].
+      #
+      # If a newly added ID goes beyond "399", it may conflict with existing
+      # system user or group of the same id in someone else's NixOS.
+      # This could break their system and make that person upset for a whole day.
+      #
+      # Sidenote: the default is defined in `shadow` module[2], and the relavent change
+      # was made way back in 2014[3].
+      #
+      # [1]: https://man7.org/linux/man-pages/man5/login.defs.5.html#:~:text=SYS_UID_MAX%20(number)%2C%20SYS_UID_MIN%20(number)
+      # [2]: <nixos/modules/programs/shadow.nix>
+      # [3]: https://github.com/NixOS/nixpkgs/commit/0e23a175de3687df8232fe118cbe87f04228ff28
 
       nixbld = 30000; # start of range of uids
       nobody = 65534;
@@ -669,7 +686,24 @@ in
 
       # When adding a gid, make sure it doesn't match an existing
       # uid. Users and groups with the same name should have equal
-      # uids and gids. Also, don't use gids above 399!
+      # uids and gids.
+      #
+      # !!! Don't use gids above "399"! !!!
+      #
+      # The reason behind this restriction is that, NixOS by default allocates
+      # system user UIDs/GIDs in the range of `400..999`. System users/groups
+      # created using command like `useradd` will have UID and GID in this range[1].
+      #
+      # If a newly added ID goes beyond "399", it may conflict with existing
+      # system user or group of the same id in someone else's NixOS.
+      # This could break their system and make that person upset for a whole day.
+      #
+      # Sidenote: the default is defined in `shadow` module[2], and the relavent change
+      # was made way back in 2014[3].
+      #
+      # [1]: https://man7.org/linux/man-pages/man5/login.defs.5.html#:~:text=SYS_UID_MAX%20(number)%2C%20SYS_UID_MIN%20(number)
+      # [2]: <nixos/modules/programs/shadow.nix>
+      # [3]: https://github.com/NixOS/nixpkgs/commit/0e23a175de3687df8232fe118cbe87f04228ff28
 
       # For exceptional cases where you really need a gid above 399, leave a
       # comment stating why.