Workflow documentation

[goosewin]

Description

• Adds Workflows Overview doc
• Adds Workflows Quickstart doc
• Adds 4 new comprehensive workflow examples with real working APIs:
  • E-commerce order management with customer tiers and return processing
  • Outbound sales with lead qualification and CRM integration
  • Medical triage with emergency routing and HIPAA compliance
  • Appointment scheduling with calendar integration
• Updates parts of existing documentation to emphasize dashboard-first approach:
  • Tools and query documentation now shows dashboard as preferred method
  • Keeps API instructions as alternatives for advanced users
  • Replaces hypothetical URLs with real testable APIs (JSONPlaceholder, OpenWeatherMap)
• Removes pizza example and redirects to inbound support

Testing Steps

• Run the app locally using fern docs dev or navigate to preview deployment
• Ensure all workflow links in left sidebar are clickable
• Review Workflows Overview and Workflows Quickstart
• Navigate to all new workflow examples in /workflows/examples/* section
• Test CSV download links work in each example
• Verify pizza example redirects to inbound support
• Check that tools/query documentation shows dashboard-first approach

[github-actions]

🌿 Preview your docs: https://vapi-preview-08461b72-62c2-4843-a856-2b04d32ad28b.docs.buildwithfern.com

[github-actions]

🌿 Preview your docs: https://vapi-preview-f3ad592b-ae3e-4fd7-96ca-0dd2437b4620.docs.buildwithfern.com

[github-actions]

📝✨ Documentation Review by Claude 🤖

Hey there! 👋 I've reviewed your documentation changes against our style guidelines. Here's what I found:

📄 fern/workflows/examples/appointment-scheduling.mdx

Documentation Review: Appointment Scheduling Workflow 📝

✅ Excellent Structure & Components 🎉

• Perfect use of <Steps> component throughout - no numbered lists detected!
• Clean, logical progression from setup to completion
• Good use of video demonstrations
• Proper MDX syntax and formatting
• Excellent sectioning with clear headings

✅ Writing Style Strengths 🚀

• Active voice: "Build an AI-powered workflow" ✓
• Present tense: "Click on it and configure" ✓
• Second person: Consistent "you" usage ✓
• Task-oriented: Clear step-by-step progression ✓
• Concrete examples: Specific prompts and configurations ✓

✅ Front Matter & Titles 🎯

• Title follows proper capitalization (only first word)
• Subtitle is clear and descriptive
• Good metadata structure

💡 Minor Improvements Needed ✨

🤔 Writing Style Refinements

• Line 26: "We will be creating" → Consider "Create an appointment scheduling workflow" (more direct)
• Line 85: "You'll start with" → "Start with" (more concise)
• Line 260: "Just like that, you've built" → Consider "You've built" (remove filler phrase)

📝 Clarity Enhancements

• Prerequisites section: Could benefit from mentioning tool configuration prerequisites
• Step 74-76: "Configure workflow variables" needs more specific instructions
• Lines 160-169: The edge condition examples seem contradictory - "if user said yes" vs intent-based routing needs clarification

🧩 Component Suggestions

• Consider adding a <Warning> callout about testing in a safe environment before production
• The phone number example +1-555-BARBER-1 could use a <Note> explaining it's placeholder text

⚠️ Technical Accuracy Questions

• Line 193: "Choose 'Check Availability' from pre-defined calendar tools" - needs verification this tool exists by default
• Edge conditions (160-169): The logic seems unclear - why would "if user said yes" route to appointment types?

💡 Enhancement Suggestions

Add helpful context callouts:

<Note>
The workflow variables mentioned in step 4 include customer information like name, phone number, and appointment preferences that will be extracted during the conversation.
</Note>

Clarify edge conditions:

<Tip>
Use AI conditions like "if the user wants to schedule" for natural language routing, or logic conditions like `{{ intent == "schedule" }}` for variable-based routing.
</Tip>

Overall Assessment: 🎉 Excellent Documentation!

This is a well-structured, comprehensive guide that properly uses MDX components and follows most style guidelines. The <Steps> implementation is perfect, and the logical flow makes it easy to follow. With minor refinements to clarity and some technical verification, this will be an outstanding workflow tutorial.

Score: 8.5/10 - Great work! 🚀

---

📄 fern/workflows/examples/clinic-triage-scheduling.mdx

Looking at your clinic triage and scheduling workflow documentation, here's my review:

✅ Excellent Work - Strong Foundation!

What's working really well:

• 🚀 Great use of <Steps> components throughout (perfect execution!)
• ✅ Clear, task-oriented structure with logical flow
• 🎯 Strong outcome focus - readers know exactly what they'll build
• ✅ Proper active voice and present tense usage
• 🎉 Excellent integration guidance for real healthcare systems
• ✅ HIPAA compliance warning is crucial and well-placed

🤔 Minor Issues to Address

Front Matter:

• ⚠️ Title should be: "Clinic triage and scheduling workflow" (only first word capitalized)
• 💡 Consider starting subtitle with "Learn to build..." for consistency with guide format

Writing Style:

• 📝 "We will be creating" → "You'll create" (more direct, second person)
• 📝 Several instances could be more active: "Build an AI-powered clinic receptionist" is good, but "We will be creating" breaks the pattern

Content Structure:

• 🤔 The knowledge base section (Section 1) feels disconnected from the main workflow. Consider integrating it into the workflow steps or making the connection clearer
• ⚠️ Some tool configuration details are quite technical - consider adding brief explanations of why each tool is needed

MDX Components:

• ✨ Great use of <Warning> for HIPAA compliance
• 💡 Consider adding a <Tip> component about testing in non-production environments
• 🧩 The video components are well-implemented

🎯 Specific Improvements

Section 1 - Knowledge Base:

# Instead of just listing downloads, explain the purpose:
These spreadsheets contain sample medical data that your workflow will reference during patient interactions.

Section 2 - Scenario:

# Change this:
"We will be creating a triage and scheduling workflow for Riverside Family Clinic"

# To this:
"You'll create a triage and scheduling workflow for Riverside Family Clinic"

🚀 Overall Assessment

This is a comprehensive, well-structured guide that effectively demonstrates complex healthcare workflow automation. The use of real healthcare system integrations and HIPAA considerations shows excellent attention to real-world implementation needs. Just a few minor style adjustments will make it perfect!

Score: 8.5/10 - Excellent content with minor style improvements needed.

---

📄 fern/workflows/examples/ecommerce-order-management.mdx

Great documentation! Here's my review of your e-commerce order management workflow:

✅ Things Done Well 🎉

Front Matter ✅

• Title follows style (only first word capitalized)
• Subtitle is clear and task-oriented

Structure & Components ✅

• Excellent use of <Steps> component throughout
• Perfect use of <Note> callouts for production notes
• Video components properly implemented
• Clear section headers with proper hierarchy

Writing Style ✅

• Active voice: "Build an AI-powered workflow" ✓
• Present tense: "Click Tools" ✓
• Second person: "you" consistently used ✓
• Concrete examples with actual code snippets ✓

Technical Content ✅

• Clear step-by-step workflow creation
• Proper tool configuration details
• Good use of code blocks for prompts and configurations
• Helpful integration examples for real systems

⚠️ Minor Improvements 🤔

Writing Style 📝

• Line 24: "We will be creating" → Consider "Create an order management workflow" (more direct)

Content Organization 💡

• Line 64: "Before building the workflow, create the necessary tools" - This context setting is good, but could be moved to intro

Consistency 🧩

• Mix of "E-commerce" and "e-commerce" - consider standardizing to "e-commerce" throughout

🎯 Specific Suggestions

Links ✨

• Lines 341-353: All integration links are descriptive (not "click here") - excellent!

Bold Usage ✅

• Good consistent bolding of key concepts like Tool Name, Node Name, etc.

Scannability ✅

• Good use of horizontal rules (---) to separate major sections
• Clear headings make it easy to scan

🚀 Overall Assessment

This is excellent documentation! It follows the style guidelines very well, uses the proper MDX components, and provides a comprehensive workflow example. The structure is logical, the writing is clear and direct, and the technical implementation details are thorough.

Score: 9/10 - Just minor style consistency improvements needed!

---

📄 fern/workflows/examples/outbound-sales.mdx

Looking at this outbound sales workflow documentation, here's my review:

🎉 Overall Excellent Work!

This is a well-structured, comprehensive guide that follows most documentation best practices. Here's what I found:

✅ Major Strengths

• Perfect use of components - You correctly used these instead of numbered lists throughout
• Clear structure and logical flow - The workflow building process is easy to follow
• Great practical examples - Specific prompts and configurations are very helpful
• Good use of callouts - components provide helpful context about JSONPlaceholder
• Concrete code examples - The API calls and configuration snippets are valuable
• Task-oriented approach - Each section clearly supports user success

⚠️ Minor Issues to Address

📝 Writing Style

• Passive voice in places:
  • "We will be creating" → "Create an outbound sales workflow"
  • "You'll start with" → "Start with"
  • "We'll modify" → "Modify the existing nodes"

🎯 Content Organization

• Long paragraphs in some sections - Consider breaking the "Scenario" paragraph into shorter chunks
• Front matter subtitle could be more concise - current version is quite long

💡 Enhancement Suggestions

1. Add more visual elements - Consider using components for any screenshots or diagrams
2. Expand Prerequisites section - Could mention API keys or specific permissions needed
3. Add troubleshooting section - Common issues users might encounter during setup

🚀 MDX Components - Well Done!

• Excellent use of <Steps> throughout
• Good implementation of <Note> callouts
• Proper video embedding
• Clean download buttons for CSV files

🎯 Quick Fixes Needed

1. Line 22: Change "We will be creating" to "Create"
2. Line 76: Change "We'll need them later" to "You'll need these later"
3. Line 175: Change "You'll start with" to "Start with"
4. Line 177: Change "We'll modify" to "Modify"

✨ This is Strong Documentation!

The technical accuracy, practical examples, and clear workflow structure make this an excellent resource for users building outbound sales workflows. The integration guidance at the end is particularly valuable for real-world implementation.

Great work on creating comprehensive, actionable documentation! 🚀

---

📄 fern/workflows/overview.mdx

(no content)

---

📄 fern/workflows/quickstart.mdx

Great job on this workflows quickstart! Here's my review:

✅ Excellent Structure & Components

• Perfect use of <Steps> component - You correctly used Steps instead of numbered lists throughout
• Good video integration - Videos are properly embedded and enhance the tutorial
• Logical flow - Clear progression from simple to complex concepts
• Proper MDX components - Nice use of <Note> callouts

✅ Writing Style Wins

• Active voice throughout - "Build a simple voice agent" ✨
• Present tense - "Click Call" not "You will click"
• Clear, action-oriented titles - Each section tells users exactly what they'll do
• Good use of bold for UI elements and key concepts

🎯 Minor Improvements

Front Matter:

- subtitle: Build a simple agent that greets users and gathers basic information using Vapi workflows.
+ subtitle: Learn to build a simple agent that greets users and gathers basic information using Vapi workflows.

Consistency in section titles:

- ## 1. Create a Workflow
- ## 2. Configure the Start Node
+ ## Create a workflow
+ ## Configure the start node

Line 30 - 📝 Passive voice fix:

- We will create a simple information-gathering agent
+ Create a simple information-gathering agent

💡 Small Enhancements

Line 162 - More specific instruction:

- Configure **Transfer Plan** with a brief summary message
+ Configure **Transfer Plan**: "Transferring user who requested human assistance"

Lines 166-168 - Simplify the Note:

- Developers can specify a phone number destination and a [transfer plan](/call-forwarding#call-transfers-mode), which lets them specify a message or a summary of the call to the person or agent picking up in the destination number before actually connecting the call.
+ Use a [transfer plan](/call-forwarding#call-transfers-mode) to provide context to the human agent before connecting the call.

🚀 Overall Assessment

This is a well-structured, comprehensive tutorial that follows documentation best practices! The use of Steps components, clear progression, and practical examples make it easy to follow. The combination of code examples, videos, and explanatory text creates an excellent learning experience.

Score: 8.5/10 - Just needs minor title case and voice adjustments!

---

📄 fern/call-forwarding.mdx

(no content)

---

📄 fern/examples/inbound-support.mdx

Documentation Review: Inbound Customer Support 📋

This is a well-structured tutorial that effectively guides users through building a banking support agent. Here's my detailed feedback:

✅ Things Done Well 🎉

Great Structure & Components:

• Perfect use of <Steps> components throughout - proper sequential instruction format
• Excellent video placement after each major section
• Clear section breaks with meaningful headings
• Good balance of explanation and action

Strong Content Quality:

• Concrete, practical example (VapiBank scenario)
• Clear capabilities and outcomes defined upfront
• Good use of code blocks with proper titles
• Helpful "Next Steps" section with relevant links

Excellent Technical Details:

• Specific file names and UI elements referenced
• Clear tool configurations with proper descriptions
• Comprehensive system prompt example

🚨 Issues That Need Fixing

Critical Error - Assistant Name Inconsistency:

• Line 270: Sets Assistant to Bobby but should be Tom (used throughout the rest of the tutorial)
• Line 291: References navigating to "Test Suites page" but then clicks "Assistants" - this is confusing

Navigation Issue:

• Section 7 step 1: Says "Navigate to Test Suites page" but then instructs to click "Assistants" - this appears to be incorrect

⚠️ Minor Issues & Improvements

Writing Style Issues:

• Line 27: "We will be creating" → use "You'll create" (second person, present tense)
• Line 221: Missing lookup_account tool in the list - only mentions get_balance and get_recent_transactions
• Line 307: "Consider the reading" → should be "Consider reading"

System Prompt Numbered Lists:

• Lines 98-99, 107-109, 112-128: Uses numbered lists (1. 2. 3.) in the system prompt - while this is within a code block for the prompt itself, consider if this follows your style guide

🎯 Specific Recommendations

1. Fix the assistant name consistency - Change "Bobby" to "Tom" on line 270
2. Clarify Section 7 navigation - Either fix the instructions or clarify the correct path
3. Add missing tool - Include lookup_account in the tool addition step (line 221)
4. Fix typo - "Consider the reading" → "Consider reading" (line 307)

💡 Optional Enhancements

• Consider adding a brief explanation of why file IDs are needed before Step 3 in Section 1
• The system prompt could benefit from a callout explaining its importance
• Consider adding expected outcomes for each major section

Overall Assessment 🚀

This is a high-quality tutorial with excellent structure and comprehensive coverage. The main issues are fixable inconsistencies rather than fundamental problems. Once the assistant name and navigation issues are resolved, this will be an exemplary piece of documentation that follows best practices for task-oriented content.

The use of MDX components is spot-on, the progression is logical, and the practical banking example makes the concepts concrete and relatable.

---

📄 fern/knowledge-base/using-query-tool.mdx

💡 Suggestions for Enhancement:

Add Intent Before Action ✨
Consider adding brief explanations of why each step matters before diving into the how.

Consistent Terminology 🎯

• Use "knowledge base" consistently (you do this well already!)
• Consider standardizing "file ID" vs "file IDs"

🧩 MDX Component Usage:

Excellent use of:

• <Info>, <Note>, <Warning>, <Tip> callouts
• <Frame> for image with caption
• Code blocks with proper language specification

Missing opportunity:

• Convert numbered lists to <Steps> components for better UX

🚀 Overall Assessment:

This documentation follows most best practices excellently! The main fixes needed are:

1. Convert numbered lists to <Steps> components
2. Fix title/header capitalization
3. Remove bold formatting from section headers

The content is clear, practical, and user-focused. Great work on providing both dashboard and API options! 🎉

---

📄 fern/overview.mdx

Here's my review of the Vapi overview documentation:

Overall Assessment 🎉

This is a well-structured overview page that effectively introduces Vapi! The use of CardGroups, clear headings, and logical flow makes it very scannable and user-friendly.

Issues to Fix 🚨

Line 7: Missing word - should be "infrastructure stack for your agents"

Line 16: Grammar error - "build" should be "built"

"Vapi began as a product built on top of voice agents"

Line 31: Typo - "ot" should be "to"

"Outputs from the LLM are spoken back to the user"

Minor Issues ⚠️

Line 123: Hyphenation inconsistency - "ins-and-outs" should be "ins and outs" (more natural)

Line 191: Redundant phrase - "connect with other developers & connect with our team" repeats "connect"

Consider: "Join our Discord to connect with other developers and our team:"

Style & Writing 📝

✅ Great job on:

• Active voice throughout ("Vapi lets you build")
• Present tense usage
• Second person ("you")
• Clear, concise sentences
• Proper use of bold for key concepts

💡 Minor suggestions:

• Line 20: The triple asterisks around "Assistants" is unusual - regular bold would be more consistent
• The tone is appropriately direct and professional

MDX Components 🧩

✅ Excellent use of:

• CardGroups for organizing content
• Proper Card component structure with titles, icons, and hrefs
• Markdown component for FAQ inclusion

🎯 All components follow best practices!

Front Matter ✅

• title: Clear and concise ✅
• subtitle: Helpful and descriptive ✅

Structure & Scannability 🚀

Excellent organization with:

• Logical progression from introduction → capabilities → examples → concepts
• Good use of headings for quick scanning
• Well-balanced content sections

Links & Navigation ✅

All links use descriptive text (no "click here" issues) and properly formatted hrefs.

Quick Fixes Needed:

1. Line 7: Add missing "for"
2. Line 16: Change "build" to "built"
3. Line 31: Fix "ot" to "to"
4. Line 123: Consider "ins and outs"
5. Line 191: Remove redundant "connect"

This is a strong overview page that effectively introduces new users to Vapi! 🎉

---

📄 fern/tools/custom-tools.mdx

Looking at your custom tools documentation, here's my review:

Overall Assessment ✅

This is a solid, comprehensive guide! The structure flows logically from dashboard approach to API configuration, with excellent real-world examples.

Major Issues 🚨

Replace numbered lists with Steps component:
Your guide uses numbered lists in several places that should be <Steps> components:

Section: "Step 1: Navigate to the Tools Section"

<Steps>
  <Step title="Open your Vapi Dashboard">
    Navigate to [Vapi Dashboard](https://dashboard.vapi.ai)
  </Step>
  <Step title="Access Tools section">
    Click **Tools** in the left sidebar
  </Step>
  <Step title="Create new tool">
    Click **Create Tool** to start building your custom tool
  </Step>
</Steps>

Section: "Step 2: Configure Your Tool"

<Steps>
  <Step title="Select tool type">
    Select "Function" for custom API integrations
  </Step>
  <Step title="Name your tool">
    Give your tool a descriptive name (e.g., "Weather Lookup")
  </Step>
  <Step title="Add description">
    Explain what your tool does
  </Step>
  <Step title="Configure tool settings">
    Set up Tool Name, Parameters, and Server URL
  </Step>
</Steps>

Same applies to the "Dashboard Configuration" and "In the Dashboard" sections.

Minor Issues ⚠️

Title capitalization: ✅ Good job following the style guide!

Link text: ✅ All links use descriptive text, not "click here"

Active voice: 🎯 A few passive voice instances to fix:

• "the assistant to match the response" → "the assistant matches the response"
• "your server is accessible" → "make your server accessible"

Suggestions ✨

Code organization: The JSON examples are excellent! Consider adding syntax highlighting to the curl commands:

curl --location 'https://api.vapi.ai/tool' \

Callout usage: 💡 Great use of the <Note> component for the OpenWeatherMap API key requirement.

Content flow: 🚀 The progression from simple dashboard use to advanced API configuration is perfect for different user levels.

Things Done Well 🎉

• ✅ Excellent real-world weather tool example
• ✅ Clear separation of dashboard vs API approaches
• ✅ Complete request/response format documentation
• ✅ Helpful video tutorial inclusion
• ✅ Good use of MDX components (Note, iframe)
• ✅ Consistent terminology throughout

Quick Fixes Needed 📝

1. 🔥 Convert all numbered lists to <Steps> components
2. 🎯 Fix the few passive voice instances mentioned above

The content quality is excellent - just needs the MDX component updates to fully align with your style guide!

---

📄 fern/docs.yml

🎉 Overall Assessment: Excellent Configuration File!

This docs.yml file is well-structured and comprehensive. It's clearly a mature documentation configuration with thoughtful organization. Here's my review:

✅ What's Working Great:

• Clear navigation hierarchy - Logical grouping from "Get started" through advanced topics
• Consistent icon usage - Font Awesome icons throughout for visual consistency
• Comprehensive redirects - Excellent maintenance of old URLs
• Good tab organization - Separates docs, API reference, SDKs, and changelog effectively
• Professional branding - Proper logo, colors, and styling configuration

💡 Areas for Enhancement:

🎯 Navigation Clarity

• Consider adding brief descriptions to major sections like "Assistant customization" to help users understand scope
• The "Resources" section is quite large - might benefit from reorganization into more focused groupings

📝 Content Organization

• Some deep nesting (4+ levels) in areas like SIP integration could be flattened for better scannability
• Consider if "Ecosystem" belongs better under integrations rather than as a standalone SDK page

✨ User Experience Improvements

• The changelog tab could benefit from featured/recent entries for quick access
• Consider adding a "Popular" or "Most Used" section to highlight key pages

🔥 Critical Issue - Missing Context

• As a YAML configuration file, this doesn't contain the actual documentation content that would need the style guidelines you mentioned (Steps components, callouts, etc.)
• The real review should happen on the .mdx content files referenced in the paths

🚀 Recommendations:

1. Content audit: Review the actual .mdx files for the style issues mentioned in your guidelines
2. User journey mapping: Consider reorganizing some sections based on common user paths
3. Analytics review: Use your PostHog/GA4 data to optimize navigation based on actual usage patterns

This is a solid foundation for a comprehensive documentation site! The structure supports good user experience and maintainability.

---

📖 Style Guidelines | Thanks for contributing! 🙏✨

[jimmyechan]

let's keep your quickstart since it's more interactive with the videos and use my new overview page since i added more screenshots.

• clip the part of all the videos that shows our overview page. the overview page is ugly (the one with the charts/graphs). i haven't worked on it at all and hoping to redesign it later
• examples are great - very relevant and realistic. appreciate the use of files and giving them to users. nice touch with adding actual endpoints to test. what is typicode - haven't hard of them? make sure its legit
• for each example, need to show how the overall workflow tree looks like. add a screenshot for each example. ideally at the top to users know what they are getting upfront. i wont have time to go through step by step to make sure evrything works, but please run through step to make sure everything checks out. biggest source of user frustration is following docs to the dot and still failing to get things working