diff --git a/nixos/doc/manual/development/settings-options.section.md b/nixos/doc/manual/development/settings-options.section.md
index ae15113567f6..030d5ae3dce0 100644
--- a/nixos/doc/manual/development/settings-options.section.md
+++ b/nixos/doc/manual/development/settings-options.section.md
@@ -199,6 +199,14 @@ have a predefined type and string generator already declared under
           }
         ```
 
+    `Implementation notes:`
+
+    - classpath includes are not implemented in pyhocon,
+      which is used for validating the HOCON output. This
+      means that if you are using classpath includes,
+      you will want to either use an alternative validator
+      or set `doCheck = false` in the format options.
+
 `pkgs.formats.json` { }
 
 :   A function taking an empty attribute set (for future extensibility)
diff --git a/pkgs/pkgs-lib/formats/hocon/default.nix b/pkgs/pkgs-lib/formats/hocon/default.nix
index d7ff1e85bda6..a5e081875b89 100644
--- a/pkgs/pkgs-lib/formats/hocon/default.nix
+++ b/pkgs/pkgs-lib/formats/hocon/default.nix
@@ -27,13 +27,9 @@ let
   '';
 in
 {
-  # https://github.com/lightbend/config/blob/main/HOCON.md
   format = {
     generator ? hocon-generator
     , validator ? hocon-validator
-    # `include classpath("")` is not implemented in pyhocon.
-    # In the case that you need this functionality,
-    # you will have to disable pyhocon validation.
     , doCheck ? true
   }: let
     hoconLib = {