diff --git a/doc/generator/sbt-openapi-codegen.md b/doc/generator/sbt-openapi-codegen.md
index aabd2e60ce..c637ee0ed5 100644
--- a/doc/generator/sbt-openapi-codegen.md
+++ b/doc/generator/sbt-openapi-codegen.md
@@ -55,6 +55,33 @@ import sttp.tapir.docs.openapi._
 val docs = TapirGeneratedEndpoints.generatedEndpoints.toOpenAPI("My Bookshop", "1.0")
 ```
 
+### Output files
+
+To expand on the `openapiUseHeadTagForObjectName` setting a little more, suppose we have the following endpoints:
+```yaml
+paths:
+  /foo:
+    get:
+      tags:
+        - Baz
+        - Foo
+    put:
+      tags: []
+  /bar:
+    get:
+      tags:
+        - Baz
+        - Bar
+```
+In this case 'head' tag for `GET /foo` and `GET /bar` would be 'Baz', and `PUT /foo` has no tags (and thus no 'head' tag).
+
+If `openapiUseHeadTagForObjectName = false` (assuming default settings for the other flags) then all endpoint definitions
+will be output to the `TapirGeneratedEndpoints.scala` file, which will contain a single `object TapirGeneratedEndpoints`.
+
+If `openapiUseHeadTagForObjectName = true`, then the  `GET /foo` and `GET /bar` endpoints would be output to a
+`Baz.scala` file, containing a single `object Baz` with those endpoint definitions; the `PUT /foo` endpoint, by dint of
+having no tags, would be output to the `TapirGeneratedEndpoints` file, along with any schema and parameter definitions.
+
 ### Limitations
 
 Currently, the generated code depends on `"io.circe" %% "circe-generic"`. In the future probably we will make the encoder/decoder json lib configurable (PRs welcome).