docs: add Terraform common troubleshooting guide

docs/terraform/common-troubleshooting.mdx

@@ -0,0 +1,116 @@
+---
+title: "Common Troubleshooting & Recipes"
+description: "Learn about overcoming API design incompatibilities when generating Terraform providers with Speakeasy."
+---
+
+# Common Troubleshooting & Recipes
+
+## Overview
+
+When generating Terraform providers from OpenAPI specifications, you might
+encounter cases where your API’s structure doesn’t naturally fit Terraform’s
+resource-oriented approach. These differences typically occur because APIs
+aren’t always designed with Terraform’s infrastructure management style in
+mind.
+
+Speakeasy’s generator identifies these design differences and offers extensions
+and customization options to address them. This enables you to produce
+effective Terraform providers, even when your API doesn’t initially match
+Terraform’s requirements, simplifying what might otherwise be challenging
+configuration tasks.
+
+## Fixing Common API Issues
+
+### Impedance Mismatch Errors
+
+An impedance mismatch error happens when Speakeasy's generator finds properties
+with different data types that need to be combined into one. This error means
+the data types don't match up correctly across API operations (such as between
+request and response data, or across different operations for the same entity),
+which can cause problems in the Terraform provider that's being created.
+
+#### Common example
+
+A typical impedance mismatch scenario occurs in the following situation:
+
+- A request takes UUID string for task assignment:
+
+```json request.json
+{
+  "taskId": "12345",
+  "assignee": "user-uuid-1"
+}
+```
+
+- The response returns a full user object for that assignee:
+
+```json response.json
+{
+  "taskId": "12345",
+  "assignee": {
+    "id": "user-uuid-1",
+    "name": "Alice Johnson"
+  }
+} 
+```
+
+When the generator attempts to merge these properties, it detects that it
+cannot reconcile the different data types (string vs object) and yields an
+impedance mismatch error.
+
+#### How to Fix the Problem
+
+Speakeasy includes built-in extensions to help fix impedance mismatch errors.
+You can use these solutions to adjust either the request or the response data:
+
+**Option 1: Override the property name**
+
+Use `x-speakeasy-name-override` to give the mismatched properties different
+names so they no longer attempt to merge:
+
+```yaml openapi.yaml
+TaskRequest:
+  type: object
+  x-speakeasy-entity: Task
+  properties:
+    taskId:
+      type: string
+    assignee:
+      type: string
+      x-speakeasy-name-override: assigneeId # Override the name to avoid merging
+```
+
+With this approach, the additional data (stored in the `assignee` response
+field) will still be available to Terraform consumers. However, there may be a
+loss of drift detection when Terraform updates the resource’s state during the
+read operation.
+
+Note: `x-speakeasy-name-override` can also be used to rename the conflicting
+property (in this case, "assignee") in the response schema to achieve the same
+effect. The key is to prevent a type collision between request and response.
+
+**Option 2: Ignore the mismatched property**
+
+Use `x-speakeasy-ignore` to exclude the problematic property from generation:
+
+```yaml openapi.yaml
+TaskResponse:
+  type: object
+  x-speakeasy-entity: Task
+  properties:
+    taskId:
+      type: string
+    assignee:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+      x-speakeasy-ignore: true # Ignore this property in the response
+```
+
+This approach will resolve the impedance mismatch by removing the
+conflicting property altogether. However, this also means that the
+property will no longer be tracked in Terraform state.
+

docs/terraform/index.mdx

@@ -48,6 +48,10 @@ Access advanced customization options for fine-grained control.
 
 Learn about supported OpenAPI schema keywords and their behavior.
 
+### [Common Troubleshooting & Recipes](/docs/terraform/common-troubleshooting)
+
+Learn about overcoming API design incompatibilities when generating Terraform providers with Speakeasy.
+
 ### [Configuration Reference](/docs/speakeasy-reference/generation/terraform-config)
 
 Complete reference for all available Terraform configuration options in the `gen.yaml` file.