observability(docs): adopt phase terminology across framework

workingmans-ai · workingmans-ai · commit 3d40c496ae00 · 2026-02-16T14:11:00.000-05:00
Changed "stage" to "phase" throughout observability framework to better
reflect the non-linear, iterative nature of the model. Phases can be
revisited and worked on concurrently, unlike sequential stages.

Changes:
- Framework page: Updated all section headings from "Stage X:" to "Phase"
  format, removed numbering from navigation cards, updated prose
- All 5 phase guides: Added phase context to subtitle frontmatter
  (e.g., "This is the INSTRUMENT phase of the observability framework")
- Removed numbered stage references throughout

Also includes from earlier consistency review:
- Framework: Added Test Suites deprecated label, Simulations pre-release
- Instrumentation: Removed Call Analysis recommendation, reordered nav cards,
  added back-link, added inter-stage bridge, removed decorative emoji
- Testing strategies: Added prerequisite reference to instrumentation
- Extraction patterns: Removed decorative emojis from comparison table
diff --git a/fern/observability/extraction-patterns.mdx b/fern/observability/extraction-patterns.mdx
@@ -1,9 +1,11 @@
 ---
 title: Choosing your extraction pattern
-subtitle: Understand the three architectural patterns for getting data out of Vapi
+subtitle: Understand the three architectural patterns for getting data out of Vapi. This is the **EXTRACT phase** of the [observability framework](/observability/framework).
 slug: observability/extraction-patterns
 ---
 
+<span className="internal-note">This page is in Rough Draft stage</span>
+
 ## Why extraction is an architectural choice
 
 Unlike traditional observability platforms (DataDog, New Relic) where data flows automatically from instrumentation to monitoring, **Vapi requires you to choose how data gets extracted** for analysis.
@@ -31,9 +33,9 @@ Vapi offers three architectural patterns for extracting observability data from
 
 | Pattern | Description | Engineering effort | Data richness | Typical users |
 |---------|-------------|-------------------|---------------|---------------|
-| **Dashboard Native** | Use Vapi's built-in Boards with scalar Structured Outputs for real-time dashboards | ⚡ Minimal (no infrastructure) | Basic (scalar fields only) | Solo founders, non-technical teams, startups |
-| **Webhook-to-External** | Build custom post-call processing that captures data via webhooks and exports to your data warehouse | 🛠️ High (requires backend infrastructure) | Rich (full object schemas, nested data) | Engineering teams, enterprises with existing data platforms |
-| **Hybrid** | Combine both approaches - use Boards for operational metrics, webhooks for deep analysis | ⚙️ Medium (partial infrastructure) | Flexible (mix of scalar and object data) | Growing teams balancing simplicity and power |
+| **Dashboard Native** | Use Vapi's built-in Boards with scalar Structured Outputs for real-time dashboards | Minimal (no infrastructure) | Basic (scalar fields only) | Solo founders, non-technical teams, startups |
+| **Webhook-to-External** | Build custom post-call processing that captures data via webhooks and exports to your data warehouse | High (requires backend infrastructure) | Rich (full object schemas, nested data) | Engineering teams, enterprises with existing data platforms |
+| **Hybrid** | Combine both approaches - use Boards for operational metrics, webhooks for deep analysis | Medium (partial infrastructure) | Flexible (mix of scalar and object data) | Growing teams balancing simplicity and power |
 
 **How to choose**: Start with Dashboard Native (fastest setup). Migrate to Hybrid or Webhook-to-External as your analytics needs grow or when you need features like Scorecard visualization or external BI tools.
 
diff --git a/fern/observability/instrumentation.mdx b/fern/observability/instrumentation.mdx
@@ -1,6 +1,6 @@
 ---
 title: Instrumentation
-subtitle: Configure your assistant to capture operational and business metrics
+subtitle: Configure your assistant to capture operational and business metrics. This is the **INSTRUMENT phase** of the [observability framework](/observability/framework).
 slug: observability/instrumentation
 ---
 
@@ -39,6 +39,8 @@ Think of instrumentation as installing sensors in your assistant:
 - What metrics will help you debug failures?
 - What data do you need for compliance or reporting?
 
+The schemas you define here become the assertions your Evals validate in the [TEST stage](/observability/testing-strategies).
+
 The "Instrumentation tools at a glance" section below shows how to configure custom instrumentation.
 
 ---
@@ -48,7 +50,7 @@ The "Instrumentation tools at a glance" section below shows how to configure cus
 | Tool                         | What it does                                                                                                                         | Configuration                                              |
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
 | **Built-in Instrumentation** | Automatic capture of call metadata (duration, cost, timestamps), transcripts, messages, tool calls, operational metrics.             | ✅ Automatic - no configuration needed                     |
-| **Structured Outputs**       | AI-powered data extraction using JSON Schema. Define custom schemas for customer info, call outcomes, sentiment analysis, summaries. | ⚙️ Configure schemas on assistant                          |
+| **Structured Outputs**       | AI-powered data extraction using JSON Schema. Define custom schemas for customer info, call outcomes, sentiment analysis, summaries. | Configure schemas on assistant                          |
 | **Call Analysis**            | Legacy feature for generating call summaries using AnalysisPlan configuration.                                                       | ⚠️ Legacy (use Structured Outputs for new implementations) |
 
 
@@ -134,7 +136,7 @@ Built-in does NOT cover:
 
 **When NOT to use**:
 
-- You only need simple call summaries (consider Call Analysis)
+- You only need simple call summaries (Structured Outputs can generate simple summaries too, but may be overkill if you don't need structured data)
 - Built-in operational metrics are sufficient
 
 → **[Configure Structured Outputs: Quickstart](/assistants/structured-outputs-quickstart)**
@@ -275,19 +277,27 @@ Start with basic business metrics (call success, customer info), then add qualit
     Set up your first custom instrumentation
   </Card>
 
-<Card
-  title="Extraction patterns"
-  icon="diagram-project"
-  href="/observability/extraction-patterns"
->
-  Choose your data extraction strategy
-</Card>
-
   <Card
     title="Testing strategies"
     icon="vial"
     href="/observability/testing-strategies"
   >
     Next stage: Validate your instrumented assistant
   </Card>
+
+  <Card
+    title="Extraction patterns"
+    icon="diagram-project"
+    href="/observability/extraction-patterns"
+  >
+    Choose your data extraction strategy
+  </Card>
+
+  <Card
+    title="Back to framework"
+    icon="arrow-left"
+    href="/observability/framework"
+  >
+    Return to the observability maturity model
+  </Card>
 </CardGroup>
diff --git a/fern/observability/monitoring.mdx b/fern/observability/monitoring.mdx
@@ -1,6 +1,6 @@
 ---
 title: Monitoring & Operating
-subtitle: Visualize trends, track operational health, and ensure production reliability
+subtitle: Visualize trends, track operational health, and ensure production reliability. This is the **MONITOR phase** of the [observability framework](/observability/framework).
 slug: observability/monitoring
 ---
 
diff --git a/fern/observability/observability-framework.mdx b/fern/observability/observability-framework.mdx
@@ -40,7 +40,7 @@ If you're just experimenting or building a demo, you might not need the full fra
 
 ## The observability maturity model
 
-Vapi's observability tools support a 5-stage progression:
+Vapi's observability tools support a 5-phase progression:
 
 ```
 ┌──────────────────────────────────────────────────────────────────┐
@@ -59,7 +59,7 @@ Vapi's observability tools support a 5-stage progression:
 
 ### This is a maturity progression, not a linear checklist
 
-You don't complete one stage and never return to it. Observability is **continuous**:
+You don't complete one phase and never return to it. Observability is **continuous**:
 
 - **Instrument** as you build new features
 - **Test** after every change
@@ -69,17 +69,17 @@ You don't complete one stage and never return to it. Observability is **continuo
 
 **For teams just starting**: Begin with INSTRUMENT + TEST (validate before production). Add EXTRACT + MONITOR as you scale. OPTIMIZE becomes natural once you have data flowing.
 
-**For experienced teams**: You're likely already monitoring production. This framework helps systematize pre-production testing (TEST stage) and formalize continuous improvement (OPTIMIZE stage).
+**For experienced teams**: You're likely already monitoring production. This framework helps systematize pre-production testing (TEST phase) and formalize continuous improvement (OPTIMIZE phase).
 
-<span className="vapi-validation">Is "maturity model" the right framing? Should we emphasize iteration more explicitly? How do customer segments (startups vs enterprises) typically progress through these stages?</span>
+<span className="vapi-validation">Is "maturity model" the right framing? Should we emphasize iteration more explicitly? How do customer segments (startups vs enterprises) typically progress through these phases?</span>
 
 ---
 
 ## How this framework maps to Vapi tools
 
-Each stage uses specific Vapi features. Here's a quick reference:
+Each phase uses specific Vapi features. Here's a quick reference:
 
-### Stage 1: INSTRUMENT
+### INSTRUMENT Phase
 
 Configure your assistant to capture operational and business metrics.
 
@@ -89,17 +89,17 @@ Configure your assistant to capture operational and business metrics.
 
 ---
 
-### Stage 2: TEST
+### TEST Phase
 
 Validate your assistant works correctly before production deployment.
 
-**What you'll use**: Evals, Simulations, Test Suites
+**What you'll use**: Evals, Simulations (Pre-release), Test Suites (⚠️ Deprecated)
 
 → **[Deep dive: Testing strategies](/observability/testing-strategies)**
 
 ---
 
-### Stage 3: EXTRACT
+### EXTRACT Phase
 
 Choose your data extraction pattern based on technical capability and analytics needs.
 
@@ -109,7 +109,7 @@ Choose your data extraction pattern based on technical capability and analytics
 
 ---
 
-### Stage 4: MONITOR
+### MONITOR Phase
 
 Visualize trends, track operational health, and catch problems early.
 
@@ -119,7 +119,7 @@ Visualize trends, track operational health, and catch problems early.
 
 ---
 
-### Stage 5: OPTIMIZE
+### OPTIMIZE Phase
 
 Use observability data to continuously improve your assistant.
 
@@ -167,47 +167,47 @@ Most teams start with Dashboard Native (simple, no engineering required), add we
 
 ## Next steps
 
-### Learn the framework stages
+### Learn the framework phases
 
 <CardGroup cols={2}>
   <Card
     title="Instrumentation"
     icon="wrench"
     href="/observability/instrumentation"
   >
-    Stage 1: Configure data capture
+    Configure data capture
   </Card>
 
   <Card
     title="Testing strategies"
     icon="vial"
     href="/observability/testing-strategies"
   >
-    Stage 2: Validate before production
+    Validate before production
   </Card>
 
   <Card
     title="Extraction patterns"
     icon="diagram-project"
     href="/observability/extraction-patterns"
   >
-    Stage 3: Choose your data pipeline
+    Choose your data pipeline
   </Card>
 
   <Card
     title="Monitoring"
     icon="chart-line"
     href="/observability/monitoring"
   >
-    Stage 4: Track operational health
+    Track operational health
   </Card>
 
   <Card
     title="Optimization workflows"
     icon="arrow-trend-up"
     href="/observability/optimization-workflows"
   >
-    Stage 5: Continuously improve
+    Continuously improve
   </Card>
 </CardGroup>
 
diff --git a/fern/observability/optimization-workflows.mdx b/fern/observability/optimization-workflows.mdx
@@ -1,11 +1,12 @@
 ---
 title: Optimization workflows
-subtitle: Use observability data to continuously improve your assistant
+subtitle: Use observability data to continuously improve your assistant.  This is the **OPTIMIZE phase** of the [observability framework](/observability/framework).
 slug: observability/optimization-workflows
 ---
 
 <span className="internal-note">This page is in Skeleton Draft stage - structure and scope for review, detailed content to be developed in iteration 2</span>
 
+
 ## What is optimization?
 
 **Optimization** is the continuous improvement loop: using observability data to refine prompts, improve tool calls, and enhance conversation flows.
diff --git a/fern/observability/testing-strategies.mdx b/fern/observability/testing-strategies.mdx
@@ -1,6 +1,6 @@
 ---
 title: Testing strategies
-subtitle: Validate your assistant works correctly before deploying to production
+subtitle: Validate your assistant works correctly before deploying to production. This is the **TEST phase** of the [observability framework](/observability/framework).
 slug: observability/testing-strategies
 ---
 
@@ -18,6 +18,8 @@ Unlike traditional software testing (unit tests, integration tests), voice AI te
 - **Edge cases** — How does the system handle interruptions, unclear requests, or unexpected inputs?
 - **Regression** — Do changes break existing functionality?
 
+Testing assumes you've already instrumented your assistant with Structured Outputs (see [Instrumentation](/observability/instrumentation)).
+
 <span className="vapi-validation">What other specific validation and/or testing uniqueness have clients reported when working with voice AI testing?</span>
 
 ---
