claude: consistently talk about spec vs description

Author: philsturgeon

claude.md

@@ -329,6 +329,21 @@ Always write "frontend" and "backend" as single words.
 
 Don't give "internet" an initial capital unless it appears at the start of a sentence.
 
+#### OpenAPI description document vs OpenAPI specification
+
+"The OpenAPI Specification" (capitalized, often abbreviated OAS) refers to the
+standard itself, published by the OpenAPI Initiative.
+
+A YAML or JSON document that describes an API and conforms to the standard is
+an "OpenAPI description" or "OpenAPI description document", not a "spec" or
+"specification".
+
+- ❌ Upload your OpenAPI spec.
+- ❌ Generate an SDK from your OpenAPI specification.
+- ✅ Upload your OpenAPI description document.
+- ✅ Generate an SDK from your OpenAPI description.
+- ✅ This guide assumes familiarity with the OpenAPI Specification.
+
 #### npm
 
 Always write "npm" in lowercase. Never capitalize as "NPM" or treat it as an acronym. See [npm branding guidelines](https://docs.npmjs.com/policies/logos-and-usage).

openapi/frameworks/trpc.mdx

@@ -1,19 +1,19 @@
 ---
-title: How To Generate an OpenAPI Spec With tRPC
+title: How To Generate an OpenAPI With tRPC
 description: "How to use tRPC to create an OpenAPI spec and create an SDK for it with Speakeasy."
 ---
 
 import { Callout } from "@/mdx/components";
 
-# How to generate an OpenAPI/Swagger spec with tRPC
+# How to generate an OpenAPI/Swagger with tRPC
 
 In this tutorial, we'll explore how to generate an OpenAPI document for our [tRPC](https://trpc.io/) API, and then we'll use this document to create an SDK using Speakeasy.
 
 Here's what we'll cover:
 
 1.  Adding `trpc-openapi` to a tRPC project.
-2.  Generating an OpenAPI specification using `trpc-openapi`.
-3.  Improving the generated OpenAPI specification for better downstream SDK generation.
+2.  Generating an OpenAPI document using `trpc-openapi`.
+3.  Improving the generated OpenAPI document for better downstream SDK generation.
 4.  Using the Speakeasy CLI to create an SDK based on the generated OpenAPI specification.
 5.  Using the Speakeasy OpenAPI extensions to improve created SDKs.
 6.  Automating this process as part of a CI/CD pipeline.
@@ -27,7 +27,7 @@ Here's what we'll cover:
 
 tRPC does not natively export OpenAPI documents, but the [`trpc-openapi`](https://github.com/jlalmes/trpc-openapi/) package adds this functionality. We'll start this tutorial by adding `trpc-openapi` to a project, and then we'll add a script to generate an OpenAPI schema and save it as a file.
 
-The quality of your OpenAPI specification will ultimately determine the quality of created SDKs and documentation, so we'll dive into ways you can improve the generated specification.
+The quality of the OpenAPI specification will ultimately determine the quality of created SDKs and documentation, so we'll dive into ways you can improve the generated specification.
 
 With our new and improved OpenAPI specification in hand, we'll take a look at how to create SDKs using Speakeasy.