diff --git a/docs/java.md b/docs/java.md
index ec5850e394..8cf8ce91c3 100644
--- a/docs/java.md
+++ b/docs/java.md
@@ -217,6 +217,14 @@ App.Builder.create()
 
 The directory to output Kubernetes manifests.
 
+If you synthesize your application using `cdk8s synth`, you must
+also pass this value to the CLI using the `--output` option or
+the `output` property in the `cdk8s.yaml` configuration file.
+Otherwise, the CLI will not know about the output directory,
+and synthesis will fail.
+
+This property is intended for internal and testing use.
+
 ---
 
 ##### `outputFileExtension`<sup>Optional</sup> <a name="org.cdk8s.AppProps.parameter.outputFileExtension"></a>
@@ -844,6 +852,14 @@ public java.lang.String getOutdir();
 
 The directory to output Kubernetes manifests.
 
+If you synthesize your application using `cdk8s synth`, you must
+also pass this value to the CLI using the `--output` option or
+the `output` property in the `cdk8s.yaml` configuration file.
+Otherwise, the CLI will not know about the output directory,
+and synthesis will fail.
+
+This property is intended for internal and testing use.
+
 ---
 
 ##### `outputFileExtension`<sup>Optional</sup> <a name="org.cdk8s.AppProps.property.outputFileExtension"></a>
diff --git a/docs/python.md b/docs/python.md
index 2832aabe7e..7f93eb7eff 100644
--- a/docs/python.md
+++ b/docs/python.md
@@ -225,6 +225,14 @@ cdk8s.App(
 
 The directory to output Kubernetes manifests.
 
+If you synthesize your application using `cdk8s synth`, you must
+also pass this value to the CLI using the `--output` option or
+the `output` property in the `cdk8s.yaml` configuration file.
+Otherwise, the CLI will not know about the output directory,
+and synthesis will fail.
+
+This property is intended for internal and testing use.
+
 ---
 
 ##### `output_file_extension`<sup>Optional</sup> <a name="cdk8s.AppProps.parameter.output_file_extension"></a>
@@ -866,6 +874,14 @@ outdir: str
 
 The directory to output Kubernetes manifests.
 
+If you synthesize your application using `cdk8s synth`, you must
+also pass this value to the CLI using the `--output` option or
+the `output` property in the `cdk8s.yaml` configuration file.
+Otherwise, the CLI will not know about the output directory,
+and synthesis will fail.
+
+This property is intended for internal and testing use.
+
 ---
 
 ##### `output_file_extension`<sup>Optional</sup> <a name="cdk8s.AppProps.property.output_file_extension"></a>
@@ -2854,6 +2870,14 @@ cdk8s.Testing.app(
 
 The directory to output Kubernetes manifests.
 
+If you synthesize your application using `cdk8s synth`, you must
+also pass this value to the CLI using the `--output` option or
+the `output` property in the `cdk8s.yaml` configuration file.
+Otherwise, the CLI will not know about the output directory,
+and synthesis will fail.
+
+This property is intended for internal and testing use.
+
 ---
 
 ###### `output_file_extension`<sup>Optional</sup> <a name="cdk8s.AppProps.parameter.output_file_extension"></a>
diff --git a/docs/typescript.md b/docs/typescript.md
index 117a43e12c..506d9f33b0 100644
--- a/docs/typescript.md
+++ b/docs/typescript.md
@@ -702,6 +702,14 @@ public readonly outdir: string;
 
 The directory to output Kubernetes manifests.
 
+If you synthesize your application using `cdk8s synth`, you must
+also pass this value to the CLI using the `--output` option or
+the `output` property in the `cdk8s.yaml` configuration file.
+Otherwise, the CLI will not know about the output directory,
+and synthesis will fail.
+
+This property is intended for internal and testing use.
+
 ---
 
 ##### `outputFileExtension`<sup>Optional</sup> <a name="cdk8s.AppProps.property.outputFileExtension"></a>
diff --git a/src/app.ts b/src/app.ts
index 04ea890a30..c0f0ce5bbe 100644
--- a/src/app.ts
+++ b/src/app.ts
@@ -23,6 +23,14 @@ export interface AppProps {
   /**
    * The directory to output Kubernetes manifests.
    *
+   * If you synthesize your application using `cdk8s synth`, you must
+   * also pass this value to the CLI using the `--output` option or
+   * the `output` property in the `cdk8s.yaml` configuration file.
+   * Otherwise, the CLI will not know about the output directory,
+   * and synthesis will fail.
+   *
+   * This property is intended for internal and testing use.
+   *
    * @default - CDK8S_OUTDIR if defined, otherwise "dist"
    */
   readonly outdir?: string;