nixos/systemd: clarify what enableStrictShellChecks checks (#401460)

nixos/modules/system/boot/systemd.nix

@@ -226,7 +226,32 @@ in
     package = mkPackageOption pkgs "systemd" { };
 
     enableStrictShellChecks = mkEnableOption "" // {
-      description = "Whether to run shellcheck on the generated scripts for systemd units.";
+      description = ''
+        Whether to run `shellcheck` on the generated scripts for systemd
+        units.
+
+        When enabled, all systemd scripts generated by NixOS will be checked
+        with `shellcheck` and any errors or warnings will cause the build to
+        fail.
+
+        This affects all scripts that have been created through the `script`,
+        `reload`, `preStart`, `postStart`, `preStop` and `postStop` options for
+        systemd services. This does not affect command lines passed directly
+        to `ExecStart`, `ExecReload`, `ExecStartPre`, `ExecStartPost`,
+        `ExecStop` or `ExecStopPost`.
+
+        It therefore also does not affect systemd units that are coming from
+        packages and that are not defined through the NixOS config. This option
+        is disabled by default, and although some services have already been
+        fixed, it is still likely that you will encounter build failures when
+        enabling this.
+
+        We encourage people to enable this option when they are willing and
+        able to submit fixes for potential build failures to Nixpkgs. The
+        option can also be enabled or disabled for individual services using
+        the `enableStrictShellChecks` option on the service itself, which will
+        take precedence over the global setting.
+      '';
     };
 
     units = mkOption {