diff --git a/docs/osm2pgsql-gen.md b/docs/osm2pgsql-gen.md
index eb81d8629..3161ced34 100644
--- a/docs/osm2pgsql-gen.md
+++ b/docs/osm2pgsql-gen.md
@@ -44,11 +44,6 @@ mandatory for short options too.
     Setting this to the number of available CPU cores is a reasonable starting
     point.
 
-\--middle-schema=SCHEMA
-:   Database schema where the `osm2pgsql_properties` table is to be found.
-    Default `public`. Set to the same value as on the `osm2pgsql` command
-    line.
-
 # HELP/VERSION OPTIONS
 
 -h, \--help
@@ -85,6 +80,16 @@ mandatory for short options too.
 -P, \--port=PORT
 :   Database server port.
 
+\--schema=SCHEMA
+:   Default for various schema settings throughout osm2pgsql-gen
+    (default: `public`). The schema must exist in the database and be writable
+    by the database user. It must be the same as used with `osm2pgsql`.
+
+\--middle-schema=SCHEMA
+:   Database schema where the `osm2pgsql_properties` table is to be found.
+    Default set with `--schema`. Set to the same value as on the `osm2pgsql`
+    command line.
+
 # SEE ALSO
 
 * [osm2pgsql website](https://osm2pgsql.org)
diff --git a/docs/osm2pgsql.md b/docs/osm2pgsql.md
index 76cbe1224..7f5a84c97 100644
--- a/docs/osm2pgsql.md
+++ b/docs/osm2pgsql.md
@@ -91,6 +91,10 @@ mandatory for short options too.
 -P, \--port=PORT
 :   Database server port.
 
+\--schema=SCHEMA
+:   Default for various schema settings throughout osm2pgsql (default: `public`).
+    The schema must exist in the database and be writable by the database user.
+
 # INPUT OPTIONS
 
 -r, \--input-reader=FORMAT
@@ -164,8 +168,10 @@ mandatory for short options too.
     as it doesn't work well with small imports. The default is disabled.
 
 \--middle-schema=SCHEMA
-:   Use PostgreSQL schema SCHEMA for all tables, indexes, and functions in
-    the middle (default is `public`).
+:   Use PostgreSQL schema SCHEMA for all tables, indexes, and functions in the
+    middle. The schema must exist in the database and be writable by the
+    database user. By default the schema set with `--schema` is used, or
+    `public` if that is not set.
 
 \--middle-way-node-index-id-shift=SHIFT
 :   Set ID shift for way node bucket index in middle. Experts only. See
@@ -274,8 +280,10 @@ mandatory for short options too.
     different projection is used for the geometries.
 
 \--output-pgsql-schema=SCHEMA
-:   Use PostgreSQL schema SCHEMA for all tables, indexes, and functions in
-    the pgsql output (default is `public`).
+:   Use PostgreSQL schema SCHEMA for all tables, indexes, and functions in the
+    pgsql output. The schema must exist in the database and be writable by the
+    database user. By default the schema set with `--schema` is used, or
+    `public` if that is not set.
 
 # EXPIRE OPTIONS