Workflow docs revision

[goosewin]

Description

• Cropped videos to remove dashboard in the first few seconds
• Removed workflows section icon
• Fixed broken link on workflows overview page
• Added new workflow screenshots to display achieved results

Testing Steps

• Run the app locally using fern docs dev or navigate to preview deployment
• Ensure that no links are broken
• Ensure that all updated video snippets make sense
• Ensure that all new and/or updated screenshots make sense

[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/overview.mdx

Looking at your workflows overview documentation, here's my review:

Overall Assessment 🎉

This is a well-structured and comprehensive overview! The content flows logically and covers all essential aspects of workflows. Great job on the visual elements and practical examples.

What's Working Well ✅

• Excellent structure: Logical progression from introduction → benefits → use cases → technical details
• Strong visual support: Good use of Frame components with descriptive alt text
• Comprehensive coverage: All node types are well-documented with clear explanations
• Practical focus: Great inclusion of best practices and real-world use cases
• Good formatting: Proper use of MDX components and consistent styling

Issues to Address 🚨

1. Front Matter - Title Capitalization 📝

# Current
title: Workflows overview

# Should be
title: Workflows overview

✅ Actually, this follows the style guide correctly (only first word capitalized)!

2. Passive Voice Issues 📝

Several instances need converting to active voice:

Current: "Workflows is a visual builder designed for creating..."
Better: "Workflows provides a visual builder that creates..."

Current: "It empowers developers and low-code builders to design agents..."
Better: "Developers and low-code builders can design agents..."

3. Missing Context for Code Examples 🤔

The condition examples need more explanation:

# Add context before showing examples
When writing conditions, you can use three approaches:

**AI-based conditions** - Written in plain language:

Minor Improvements ⚠️

4. Inconsistent Terminology 🎯

• "note" vs "node" - should be consistently "node"
• "Workflows" vs "workflows" - be consistent with capitalization

5. Link Text Enhancement 💡

Current: "Check out these resources:"
Better: More descriptive link text in the bullets themselves

6. Paragraph Length 📝

Some paragraphs are quite long, especially in the introduction. Consider breaking this down:

"Workflows is a visual builder designed for creating robust, deterministic conversation flows. It empowers developers and low-code builders to design agents through an intuitive interface representing interactions via nodes and edges."

Could become two shorter paragraphs.

Content Suggestions ✨

7. Add Success Metrics 💡

Consider adding a brief section on what successful workflow implementation looks like.

8. Troubleshooting Hints 🧩

A brief troubleshooting section or common pitfalls would be valuable.

Technical Accuracy ✅

• All MDX components are used correctly
• Image paths and alt text are appropriate
• Warning component is used effectively
• Steps component isn't needed here (no sequential instructions)

Final Grade: B+ 🚀

This is solid documentation that serves its purpose well. The main improvements needed are writing style refinements (active voice, shorter paragraphs) and adding a bit more context around code examples. The structure and content coverage are excellent!

Priority fixes: Convert passive voice instances and add context to condition examples.
Nice-to-haves: Break up longer paragraphs and add troubleshooting section.

---

📄 fern/docs.yml

I've reviewed the docs.yml configuration file! This is actually a configuration file, not documentation content, so most of the content guidelines don't directly apply. However, I can provide feedback on the structure and organization:

✅ What's Working Well

🎉 Excellent organization - The navigation structure is logical and well-hierarchical
🚀 Comprehensive coverage - Great breadth of topics from quickstart to advanced features
✨ Good use of icons - FontAwesome icons add visual clarity throughout
🎯 Smart redirects - Extensive redirect mapping preserves SEO and user experience

💡 Suggestions for Improvement

Navigation Structure

⚠️ Some sections could be streamlined:

• The "Resources" section is quite large - consider breaking it into smaller, more focused sections
• "Community" section is collapsed but has external links mixed with internal content

Consistency Issues

🤔 Minor inconsistencies in naming:

• Some paths use hyphens (call-analysis) while others use underscores in redirects
• Mix of "Quickstart" vs "Get started" terminology

Content Organization

📝 Consider these improvements:

• The "Examples" section under "Get started" might work better as its own top-level section
• "Workflows" could potentially be integrated into the main flow rather than standalone

🎯 Specific Technical Notes

✅ Good practices observed:

• Proper YAML structure and syntax
• Comprehensive analytics setup
• Well-configured branding and styling
• Extensive redirect mapping for backward compatibility

This configuration file is well-structured and comprehensive! The main opportunities are around simplifying the navigation hierarchy and ensuring consistent naming conventions throughout.

---

📖 Style Guidelines | Thanks for contributing! 🙏✨

[github-actions]

🌿 Preview your docs: https://vapi-preview-4227cf40-94d9-41e4-b729-24a4f8aaf90d.docs.buildwithfern.com

[github-actions]

🌿 Preview your docs: https://vapi-preview-137c41b5-5285-4f92-b135-fcff9ef09cc1.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/examples/voice-widget.mdx

Looking at your voice widget documentation, here's my review:

✅ What's Working Well

🎉 Excellent use of <Steps> component - You're properly using the MDX Steps component instead of numbered lists!

🚀 Great code examples - The HTML, JavaScript, and configuration snippets are comprehensive and practical

✅ Good structure - Logical flow from installation to customization

✅ Proper front matter - Title and subtitle are clear and helpful

🚨 Major Issues to Fix

🔥 Passive voice in subtitle: "This robust tool enables your visitors to engage..."

• Fix: Change to active voice like "Enable your visitors to engage with a voice assistant..."

🔥 Inconsistent section heading: "Steps for Installation" should just be "Installation" to match the pattern

⚠️ Minor Issues & Improvements

📝 Opening paragraph is wordy: "This robust tool enables your visitors to engage with a voice assistant for support and interaction, offering a smooth and contemporary way to connect with your services."

• Suggestion: Simplify to "Add a voice assistant to your website. Visitors can ask questions and get support through natural conversation."

🤔 Step 2 title: "Generate Your Assistant" - should be "Create your assistant" (more direct, active voice)

🤔 Step 3 title: "Modify the Button" could be "Customize the button" (more descriptive)

💡 Missing context in Step 4: The code example jumps into event listeners without explaining what EventSource means or why you'd want to listen to these events.

🎯 Specific Improvements

📝 Replace placeholder text: Instead of "Substitute with your assistant ID" use "Replace with your assistant ID"

💡 Add brief explanations before code blocks in Step 4:

Listen to widget events to customize behavior based on call state:

⚠️ Inconsistent terminology: You use both "bot" and "assistant" - stick with "assistant" throughout

✨ Enhancement Suggestions

🧩 Consider adding a callout about where to find the assistant ID in the dashboard

💡 UI Customization section could benefit from a brief example showing how to override one of the CSS classes

Overall, this is solid documentation with good structure and examples! The main fixes are converting to active voice and simplifying some wordy sections. The use of Steps component is perfect! 🚀

---

📄 fern/quickstart/dashboard.mdx

Documentation Review: Dashboard Quickstart 🚀

Overall, this is an excellent quickstart guide! It follows most guidelines well and provides a clear, task-oriented approach. Here's my detailed feedback:

✅ What's Working Well 🎉

• Perfect use of <Steps> components throughout - exactly as guidelines require!
• Great structure and flow - logical progression from creation to testing
• Excellent use of frames with proper captions for visual aids
• Good balance of explanation and action - tells users what they're doing and why
• Consistent terminology - STT, LLM, TTS used throughout
• Active voice used effectively ("Select your preferred provider")
• Present tense maintained ("Go to dashboard.vapi.ai")

🚨 Critical Issue to Fix

Lines 127-128: Numbered list inside <Steps>

1. Fill out <strong>your own phone number</strong> as the number to dial.
2. Set the assistant that will be making the call

🎯 Fix: Convert to individual <Step> components:

<Step title="Fill out your phone number">
  Enter your own phone number as the number to dial.
</Step>
<Step title="Set the assistant">
  Select the assistant that will be making the call.
</Step>

⚠️ Minor Improvements 🤔

Front Matter

• Line 3: Extra space in subtitle - remove one space after the colon

Writing Style

• Line 9: Triple asterisks (***assistants***) - consider using bold (**assistants**) instead
• Line 81: "Vapi was made for model selection to be configurable" - awkward phrasing. Consider: "Vapi allows flexible model selection"
• Line 115: "have a conversation with them" - could be "have a conversation with the caller"

Content Clarity

• Line 66: "(default gpt-4o)" - consider making this clearer: "The default model is gpt-4o"
• Line 137: "hang-up" should be "hang up" (no hyphen needed)

💡 Enhancement Suggestions ✨

Missing Context

• Consider adding a brief explanation of what each model type does before the configuration steps
• Could benefit from estimated time expectations for each major section

Frame Improvements

• Line 110: Frame caption doesn't match the step action - it says "Attach" but the step is "Create"

🧩 MDX Component Usage

Perfect! Excellent use of:

• <Steps> and <Step> components ✅
• <Frame> with proper captions ✅
• <Tip> callouts appropriately ✅
• Proper nesting of components ✅

📝 Style Compliance

• Titles: ✅ Proper capitalization
• Active voice: ✅ Mostly used well
• Present tense: ✅ Consistent
• Second person: ✅ Good use of "you"
• Bold for key concepts: ✅ Well applied

Final Score: 8.5/10 🌟

This is a high-quality quickstart guide that just needs one critical fix (the numbered list) and some minor polishing. The structure, flow, and component usage are exemplary!

---

📄 fern/snippets/quickstart/dashboard/assistant-setup-inbound.mdx

Documentation Review

Overall, this is a well-structured quickstart guide with good use of MDX components! Here's my detailed feedback:

✅ What's Working Well

• 🎉 Great MDX Component Usage: Proper use of <AccordionGroup>, <Accordion>, <Frame>, and callout components
• 🚀 Excellent Visual Support: Good use of screenshots with descriptive captions
• ✅ Logical Flow: Clear progression from sign-up through voice setup
• 🎯 Appropriate Callouts: Good use of <Info>, <Note>, and <Warning> components

🚨 Critical Issues to Fix

🔥 Numbered Lists in System Prompt (Lines 114-118)

1) There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza
2) There are 3 kinds of sides: french fries, garlic bread, and chicken wings  
3) There are 2 kinds of drinks: soda, and water.

This is inside a code block for the system prompt, so it's actually correct to keep as numbered lists since it's prompt content, not documentation steps.

⚠️ Minor Issues & Improvements

📝 Grammar & Style Issues:

• Line 50: "it's voice pipeline" → "its voice pipeline" (possessive, not contraction)
• Line 3: "signed-up" → "signed up" (no hyphen needed)
• Line 9: "Sign-up" → "Sign up" (verb form, no hyphen)

🤔 Writing Style Suggestions:

• Line 65: "It is most ideal" → "It's ideal" (more direct)
• Line 71: "it'd be ideal for you to go & set up" → "set up" (more concise)
• Line 103: Link text could be more descriptive than "OpenAI docs"

💡 Consistency Improvements:

• Mix of "log-in/login" and "sign-up/signup" - consider standardizing
• Some sentences are quite long and could be broken up for better readability

✨ Content Suggestions

🎯 Missing Context:

• Consider adding a brief intro explaining what this accordion group covers
• The system prompt example is quite long - consider mentioning users can customize it

🧩 Component Optimization:

• All accordions are appropriately used for this type of setup guide
• Frame captions are helpful and descriptive

🎉 Overall Assessment

This is a solid quickstart guide that follows most documentation best practices! The main issues are minor grammar/style points. The structure is excellent and the MDX components are used appropriately. Great work on the visual documentation with screenshots and clear step-by-step guidance.

Priority fixes: Grammar corrections, especially the possessive "its" on line 50.

---

📄 fern/workflows/overview.mdx

📋 Workflows Overview Documentation Review

This is a well-structured overview document! Here's my detailed feedback against the documentation guidelines:

✅ What's Working Well

🎉 Front Matter: Perfect title and subtitle format - concise and follows the "Learn to..." pattern
🚀 Structure: Logical flow from introduction to concepts to best practices
✨ MDX Components: Excellent use of <Frame> components for images and proper <Warning> callout
🎯 Content Coverage: Comprehensive overview of all node types and workflow concepts
💡 Code Examples: Good use of code blocks for condition examples

🚨 Major Issues to Fix

1. Grammar & Style Issues

Line 31: "Workflows consists of node and edges" → "Workflows consist of nodes and edges"
Line 33: "different type of note" → "different type of node"
Line 56: "agents heavily depend" → "agents heavily depends" (subject-verb agreement)

2. Inconsistent Indentation

Lines 10, 41, 76, 94, 102, 114: Extra space before <Frame> tags - should align consistently

⚠️ Minor Issues & Improvements

Writing Style

📝 Line 50: "waiting for user" → "waiting for the user"
📝 Line 60: "e.g. when user wants" → "e.g., when the user wants"
📝 Line 112: Remove trailing space after "configurations."

Content Clarity

🤔 Line 64: "Single Prompt Assistants" - consider linking this or briefly explaining what these are
🤔 Lines 70-74: The bullet list for variable configuration could be more scannable

💡 Suggestions for Enhancement

1. Add Context for Complex Terms

Consider briefly explaining "Single Prompt Assistants" when first mentioned, or link to relevant documentation.

2. Improve Scannability

The variable configuration section (lines 70-74) could benefit from better formatting:

Variables can be configured by:
- **Variable name and data type**: String, Number, Boolean, Integer
- **Extraction prompt**: Clear description to guide data extraction
- **Enums for String types**: Constrain values to specific sets

3. Consistent Voice

🎯 Most of the document uses active voice well, but there are a few passive constructions that could be improved:

• "must be formatted" could be "format request bodies"
• "can be configured" could be "configure variables"

✨ Excellent Practices Observed

🚀 Task-Oriented Structure: Each section clearly explains what users can accomplish
🎯 Concrete Examples: Great code examples for conditions and liquid syntax
✅ Proper MDX Usage: Correct use of Frame, Warning components
🧩 Logical Flow: Natural progression from concepts to implementation to best practices
📝 Descriptive Links: All links use descriptive text instead of "click here"

🎯 Priority Fixes

1. Fix grammar errors (lines 31, 33, 56)
2. Standardize Frame component indentation
3. Add articles ("the user" instead of "user")
4. Consider adding brief context for "Single Prompt Assistants"

Overall, this is a solid overview document that effectively introduces Workflows concepts. The structure is logical, the content is comprehensive, and it follows most documentation best practices. Just need those small grammar and formatting fixes! 🎉

---

📄 fern/docs.yml

Looking at this docs.yml configuration file, I can see this is a Fern documentation configuration rather than a typical MDX documentation file. Since this is a YAML configuration file that defines the structure and settings for a documentation site, most of the content guidelines don't directly apply here.

However, I can review it against documentation best practices for configuration and navigation:

✅ Things Done Well

🎉 Excellent navigation structure - The hierarchical organization with clear sections like "Get started", "Assistant customization", "Workflows" etc. makes it easy for users to find what they need

🚀 Consistent iconography - Good use of Font Awesome icons throughout the navigation that help users visually identify different sections

✅ Proper redirects setup - Comprehensive redirect configuration ensures users don't hit dead links when URLs change

🎯 Clear tab organization - Separating Documentation, API Reference, SDKs, and Changelog into distinct tabs creates logical content groupings

💡 Minor Suggestions

📝 Navigation labels could be more task-oriented - Some sections could benefit from action-oriented labels:

• "Assistant customization" → "Customize assistants"
• "Best practices" → "Optimize performance" or "Test and improve"

🤔 Consider grouping similar concepts - The "Phone numbers" and "Calls" sections have some overlap that could be streamlined

⚠️ Accessibility consideration - While icons are great visually, ensure they have proper alt text/labels for screen readers (this may be handled by Fern automatically)

🎯 Specific Improvements

✨ Navigation depth - Some sections go quite deep (4+ levels). Consider if all nested levels are necessary for user comprehension

💡 Section ordering - Consider if the current order matches typical user journeys (e.g., users might want "Testing" closer to "Get started")

Overall, this is a well-structured documentation configuration that should provide users with clear pathways to find the information they need! 🚀

---

📖 Style Guidelines | Thanks for contributing! 🙏✨

[github-actions]

🌿 Preview your docs: https://vapi-preview-8e52c994-a083-4194-b196-d5571117eac5.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/examples/voice-widget.mdx

(no content)

---

📄 fern/quickstart/dashboard.mdx

Looking at your quickstart documentation, this is a really solid foundation! 🎉 The structure is clear and the content flows logically. Here's my detailed review:

✅ Things Done Well

Structure & Flow: Your step-by-step approach is perfect for a quickstart guide. The progression from creating an assistant → configuring models → making calls is logical and user-friendly.

MDX Components: Great use of <Steps> components throughout! This is exactly what we want to see instead of numbered lists.

Visual Support: Excellent use of GIFs and images with proper <Frame> components and descriptive captions.

🚨 Major Issues to Fix

Numbered Lists: You have a numbered list in the "Make an outbound call" section that should use <Steps>:

1. Fill out <strong>your own phone number</strong> as the number to dial.
2. Set the assistant that will be making the call

Should be:

<Steps>
  <Step title="Enter your phone number">
    Fill out **your own phone number** as the number to dial.
  </Step>
  <Step title="Select your assistant">
    Set the assistant that will be making the call.
  </Step>
</Steps>

⚠️ Minor Issues & Improvements

Title Capitalization: Your subtitle has unnecessary capitalization:

• Current: subtitle: Learn to build a voice agent in under 5 minutes.
• Should be: subtitle: Learn to build a voice agent in under 5 minutes

Bold vs HTML: Inconsistent formatting - use markdown **bold** instead of <strong>:

• Change <strong>your own phone number</strong> → **your own phone number**

💡 Suggestions for Enhancement

Truncated Content: The system prompt example cuts off with "..." - consider either showing the full prompt or adding a note about where to find the complete version.

Missing Context: In the outbound call section, you could add a brief explanation of why someone would want to make an outbound call before jumping into the steps.

📝 Writing Style Notes

Active Voice: Generally good! Most instructions use active voice effectively.

Present Tense: Consistent throughout - well done!

Second Person: Proper use of "you" throughout.

🎯 Specific Recommendations

1. Fix the numbered list in the outbound section using <Steps>
2. Remove the period from the subtitle
3. Replace <strong> tags with markdown bold
4. Consider expanding the system prompt example or linking to a full version

Overall, this is a strong quickstart guide that follows most best practices! 🚀 The main fix needed is converting that numbered list to use the proper <Steps> component.

---

📄 fern/snippets/quickstart/dashboard/assistant-setup-inbound.mdx

Looking at this documentation file, here's my review:

✅ What's Working Well

🎉 Excellent structure: The nested accordion approach works perfectly for this complex setup process
🚀 Great visual support: Screenshots with descriptive captions help users verify they're on track
✅ Good use of callouts: Info, Note, and Warning components provide helpful context
🎯 Task-oriented flow: Logical progression from signup → assistant creation → configuration

🚨 Major Issues

🔥 Numbered lists need conversion: The system prompt section uses numbered lists (1, 2, 3) which should be converted to the <Steps> component:

<Steps>
  <Step title="Pizza options">
    There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza (often called "veggie" pizza).
  </Step>
  <Step title="Side options">
    There are 3 kinds of sides: french fries, garlic bread, and chicken wings.
  </Step>
  <Step title="Drink options">
    There are 2 kinds of drinks: soda, and water.
  </Step>
</Steps>

⚠️ Minor Issues & Improvements

📝 Inconsistent hyphenation: "Sign-up" vs "sign up" - choose one style and stick with it
🤔 Link text: "OpenAI docs" could be more descriptive like "OpenAI's prompt engineering guide"
⚠️ Redundant captions: Some image captions repeat information already in the text

💡 Suggestions

✨ Consider breaking up long accordions: The "Model Setup" section is quite dense - could split system prompt into its own top-level accordion
🧩 Code block language: Add language identifier to the system prompt code block: text
🎯 Terminology consistency: Use "dashboard" consistently instead of mixing "dashboard" and "web dashboard"

🎉 Overall Assessment

This is a well-structured, comprehensive guide! The accordion organization makes the complex setup process manageable. Just fix the numbered lists and polish the minor inconsistencies, and this will be excellent user-facing documentation.

---

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

Looking at your appointment scheduling workflow documentation, here's my review:

✅ What's Working Well

🎉 Excellent use of MDX components: Great job using <Steps> instead of numbered lists throughout!
🚀 Clear structure: The logical flow from knowledge base → workflow → phone configuration is perfect
✅ Task-oriented approach: Each section builds toward the working appointment system
🎯 Good use of code blocks: The prompts and configurations are clearly formatted

🚨 Major Issues to Fix

Front Matter Problems

🔥 Missing description: The front matter has a description field that's not standard - remove it and keep only title, subtitle, and slug

Writing Style Issues

📝 Passive voice throughout: Many instances need conversion to active voice:

• "We will be creating" → "Create an appointment scheduling workflow"
• "You'll start with" → "Start with the default template"
• "This tool will use" → "This tool uses"

📝 Inconsistent tense: Mix of future and present tense - standardize to present:

• "We'll need them later" → "You need them later"
• "You'll receive" → "You receive"

⚠️ Minor Issues & Improvements

Title Formatting

🤔 Title case in steps: Many step titles use title case instead of sentence case:

• "Download the spreadsheets" ✅ (correct)
• "Configure Workflow Settings" → "Configure workflow settings"
• "Add Customer Verification Node" → "Add customer verification node"

Link Text

⚠️ Non-descriptive links: Some links could be more descriptive:

• "dashboard.vapi.ai" → "Vapi dashboard"

Content Organization

💡 Long code blocks: Some prompts are quite lengthy - consider breaking them into shorter, more scannable sections

Consistency

🤔 Variable formatting: Mix of bold and code formatting for variables - pick one style and stick with it

🎯 Specific Fixes Needed

1. Remove the description field from front matter
2. Convert passive constructions like "will be creating" to "create"
3. Use sentence case for all step titles
4. Standardize to present tense throughout
5. Make link text more descriptive

💡 Enhancement Suggestions

✨ Add outcome callouts: Consider adding <Check> components to show what success looks like after key steps

✨ Break up long prompts: Some conversation node prompts could be split into bullet points for better scannability

✨ Add troubleshooting: A quick troubleshooting section for common workflow issues would be helpful

Overall Assessment

🚀 This is a solid, comprehensive guide with excellent use of components and clear structure. The main issues are writing style consistency and some formatting details. Once you address the passive voice and tense issues, this will be a top-tier documentation piece!

---

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

🎯 Action Items Summary

High Priority:

• Shorten the subtitle for better scannability
• Convert "We will be creating..." to "You'll create..." (active voice)

Medium Priority:

• Consider using tabs for the node configurations in step 4.4
• Add language tags to code blocks where appropriate
• Break up longer paragraphs in the routing section

Low Priority:

• Consider adding more specific examples for emergency keyword detection

Overall, this is a very strong piece of documentation 🌟 that demonstrates excellent understanding of both the technical platform and the medical domain. The structure is logical, the examples are practical, and the safety considerations are appropriate for healthcare applications.

The document successfully balances technical detail with accessibility, making it valuable for developers implementing medical AI workflows. Great work! 🎉

---

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

Review Summary ✅

This is a well-structured and comprehensive documentation that follows most guidelines effectively! Here's my detailed feedback:

🎉 What's Done Well

✅ Excellent Structure & Organization

• Clear progression from prerequisites to implementation
• Logical step-by-step workflow building
• Good use of sections and subsections
• Comprehensive coverage of the topic

✅ Great Use of MDX Components

• Proper <Steps> component usage throughout
• Effective <Note> callouts for important clarifications
• Good video integration for visual learning
• Proper download components for resources

✅ Strong Technical Content

• Realistic e-commerce scenarios
• Comprehensive workflow design
• Good integration examples with real platforms
• Practical next steps section

🔥 Issues That Need Fixing

🚨 Front Matter Problems

# Current subtitle is too long and not following guidelines
subtitle: Build an AI customer service workflow that handles orders, returns, and support using Vapi workflows.

# Should be concise, ideally under 10 words:
subtitle: Learn to automate e-commerce customer service with AI workflows

📝 Writing Style Issues

• Some sentences could be shorter and more direct
• A few instances of passive voice that should be active
• Some paragraphs are quite long and could be broken up

⚠️ Minor Improvements Needed

🎯 Specific Content Fixes:

1. Step 4, Step 1 - The prompt section is quite lengthy. Consider breaking into shorter, more scannable bullet points.

2. Global Node Section - The condition {{ customer_tier == "VIP" or total_orders > 50 or lifetime_value > 5000 }} needs better explanation of where these variables come from.

3. Integration Section - Could benefit from more specific examples of how to replace JSONPlaceholder with real APIs.

💡 Enhancement Suggestions:

1. Add a Quick Start section at the beginning showing the core workflow in 3-4 high-level steps

2. Include estimated time for completion (e.g., "⏱️ Estimated time: 45 minutes")

3. Add troubleshooting section for common workflow issues

4. Consider adding a diagram showing the workflow flow visually

🧩 Component Usage Review

✅ Excellent:

• <Steps> used correctly throughout
• <Note> callouts well-placed
• Video integration is perfect
• Download components work well

🤔 Could Improve:

• Consider using <Tip> callouts for best practices
• Some long code blocks could benefit from syntax highlighting specification

Overall Assessment: 🚀

This is a high-quality documentation piece that provides real value to users building e-commerce workflows. The structure is logical, the examples are practical, and the technical depth is appropriate. With the minor fixes above, this would be an exemplary piece of documentation!

Priority fixes: Front matter subtitle and breaking up some longer content sections for better scannability.

---

📄 fern/workflows/overview.mdx

Looking at your workflows overview documentation, here's my review:

🎉 What's Working Well

✅ Great structure - Clear logical flow from introduction through implementation details
✅ Excellent use of Frames - All images properly wrapped with descriptive alt text
✅ Strong best practices section - Comprehensive guidance for users
✅ Good use of Warning callout - Important information about End Call Nodes
✅ Active voice throughout - "Configure with an optional closing message" vs passive alternatives

🔥 Major Issues to Fix

🚨 Title capitalization - Should be "Workflows overview" not "Workflows Overview" (only first word capitalized)

🚨 Missing Steps component - The "Best practices for conditions" section uses bullet points that could be sequential steps. Consider if these should be <Steps> instead.

⚠️ Minor Improvements

🤔 Redundant phrasing - "Workflows is a visual builder" → "Workflows are a visual builder" (subject-verb agreement)

🤔 Passive voice instances:

• "Variables can be configured by:" → "Configure variables by:"
• "Request bodies must be formatted" → "Format request bodies"

📝 Writing style tweaks:

• "It empowers developers and low-code builders" → "It helps developers and low-code builders" (simpler language)
• "via nodes and edges" → "using nodes and edges" (more conversational)

💡 Suggestions for Enhancement

✨ Add outcome-focused intro - Consider starting with what users will accomplish: "Build deterministic conversation flows that handle complex customer interactions reliably."

🧩 Consider Tip callouts - The variable extraction explanation could benefit from a <Tip> callout to highlight this powerful feature.

🎯 Strengthen transitions - Add brief connecting sentences between major sections to improve flow.

🚀 Overall Assessment

This is solid documentation with good technical depth and practical guidance. The main fixes are quick style adjustments. The content successfully balances conceptual overview with actionable implementation details. Great work on the comprehensive best practices section!

---

📄 fern/docs.yml

Looking at your docs.yml configuration file, this is well-structured for a documentation site! Here's my review:

✅ What's Working Well

🎉 Excellent organization - Clear tab structure with logical groupings
🚀 Comprehensive navigation - Good depth and breadth of content coverage
✨ Consistent iconography - FontAwesome icons used thoughtfully throughout
🎯 Smart redirects - Extensive redirect mapping preserves SEO and user experience

💡 Minor Suggestions for Improvement

⚠️ Inconsistent capitalization in navigation titles:

• Some use title case: "Get started", "Assistant customization"
• Others use sentence case: "Best practices", "Phone numbers"
• Recommendation: Stick to sentence case throughout for consistency with your style guide

📝 Consider rewording some navigation labels:

• "Learn to..." pattern isn't used in section titles (only mentioned for guide subtitles)
• Current labels are actually good - direct and task-oriented

🤔 Potential navigation depth concern:

• Some sections go quite deep (4+ levels)
• Users might get lost in deeply nested content
• Consider: Flattening some hierarchies or using tabs/component organization

🎯 Specific Improvements

Navigation consistency:

# Current mixed approach:
- section: Get started  # sentence case
- section: Assistant customization  # sentence case  
- section: Best practices  # sentence case ✅

# But also:
- page: Make a web call  # sentence case ✅
- page: Core models  # sentence case ✅

Icon consistency check:
Most icons follow good patterns, but verify all FontAwesome classes are valid and consistent in style (all fa-light vs mixed weights).

✅ Overall Assessment

This is a solid documentation configuration! The structure supports user success with logical groupings and clear navigation paths. The extensive redirect list shows good maintenance practices.

🚀 Ready to ship with just minor consistency tweaks!

---

📄 fern/workflows/examples/lead-qualification.mdx

🚀 Overall Assessment

This documentation is excellent quality with only minor issues to address. The structure is logical, the content is comprehensive, and the MDX components are used correctly. The main critical fix needed is updating the file paths to match the renamed directory structure.

Priority Fixes:

1. 🔥 Update spreadsheet file paths from "outbound-sales" to "lead-qualification"
2. 💡 Consider adding the enhancement suggestions for completeness

Strengths:

• ✅ Perfect use of Steps components instead of numbered lists
• ✅ Clear, actionable instructions
• ✅ Good balance of explanation and implementation
• ✅ Proper tone and voice throughout
• ✅ Excellent integration examples and next steps

This documentation successfully guides users through building a sophisticated sales qualification workflow while maintaining clarity and professional tone throughout!

---

📖 Style Guidelines | Thanks for contributing! 🙏✨

[github-actions]

🌿 Preview your docs: https://vapi-preview-fcd2c830-b02c-4dde-87dd-a260a571e394.docs.buildwithfern.com

[github-actions]

🌿 Preview your docs: https://vapi-preview-ed93f27a-1e77-4dee-87f7-f42fb9801c20.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/examples/voice-widget.mdx

Looking at your voice-widget.mdx file, here's my review:

Overall Assessment ✅

This is a well-structured tutorial that follows most documentation best practices! The use of the <Steps> component is perfect for the sequential installation process.

Issues to Fix

🚨 Major Issues

Title Capitalization

• Current: "Web Snippet"
• Should be: "Web snippet" (only first word capitalized)

Subtitle Clarity 📝

• Current subtitle is quite long and generic
• Consider: "Learn to add a voice assistant widget to your website"

⚠️ Minor Issues

Section Heading Style 📝

• "Steps for Installation" → "Installation" (more concise)
• The steps already indicate it's a process

Passive Voice in Introduction 📝

• "This robust tool enables your visitors to engage" → "Your visitors can engage with a voice assistant"
• More direct and active

Code Comment Style 🎯

• "Substitute with your assistant ID" → "Replace with your assistant ID"
• "Substitute" is less common than "replace"

Suggestions for Improvement

💡 Content Enhancement

Consider adding:

• A brief intro about what the widget looks like/does before diving into installation
• Expected outcome after each step
• Troubleshooting section for common issues

✨ Structure Suggestions

• Move the customization sections higher in priority if they're commonly needed
• Consider grouping the event listeners example with other functionality

What's Done Well 🎉

• ✅ Perfect use of <Steps> component instead of numbered lists
• ✅ Clear, practical code examples with explanations
• ✅ Good logical flow from basic setup to advanced customization
• ✅ Comprehensive configuration options shown
• ✅ Active voice used in most places
• ✅ Present tense throughout
• ✅ Good use of code blocks with proper syntax highlighting

Quick Fixes Needed 🎯

1. Change title to "Web snippet"
2. Shorten subtitle to be more task-oriented
3. Rename "Steps for Installation" to "Installation"
4. Convert passive voice in intro to active voice

This is solid documentation that just needs minor polish! 🚀

---

📄 fern/quickstart/dashboard.mdx

Looking at your fern/quickstart/dashboard.mdx file, here's my review:

✅ Excellent Work Overall! 🎉

Your documentation follows most best practices beautifully. Here's what you're doing great:

• Perfect MDX usage: You're correctly using <Steps> components instead of numbered lists 🚀
• Clear structure: Logical progression from overview to hands-on tasks ✨
• Good front matter: Title is clear and subtitle follows the "Learn to..." pattern 🎯
• Active voice: Most content uses proper active voice and present tense ✅
• Helpful visuals: Great use of GIFs and frames with descriptive captions 📸

🤔 Minor Issues to Address

📝 Writing Style Issues

1. Subtitle formatting: Remove the extra space before "Learn"

   # Current
   subtitle:  Learn to build a voice agent in under 5 minutes.
   # Should be
   subtitle: Learn to build a voice agent in under 5 minutes.

2. Bold usage inconsistency: You have some inconsistent bold formatting

   • Line: "Each assistant has three components:" - consider making the components themselves bold
   • Consider: "Each assistant has three components: Speech-to-text (STT), Language model (LLM) and Text-to-speech (TTS)"

3. List formatting in step: In the outbound call section, you mix numbered list with Steps component

   # Current
   1. Fill out <strong>your own phone number</strong> as the number to dial.
   2. Set the assistant that will be making the call
   
   # Should be
   Fill out **your own phone number** as the number to dial and set the assistant that will be making the call.

💡 Content Suggestions

4. Missing context: The long system prompt is truncated with "..." - consider either showing the full prompt or adding a note about where to find the complete version

5. Consistency: Use consistent terminology - you switch between "callers" and "them" when referring to people calling the assistant

🎯 Specific Improvements

• Replace <strong> HTML tags with ** markdown formatting for consistency
• Consider adding a brief explanation of what happens during the call before the steps
• The tip about model selection could be more specific about what to try

🚀 Overall Assessment

This is solid documentation that follows Vapi's style guidelines well. The issues are minor polish items rather than structural problems. Great job using Steps components properly and maintaining a task-oriented approach throughout!

---

📄 fern/snippets/quickstart/dashboard/assistant-setup-inbound.mdx

Documentation Review for assistant-setup-inbound.mdx

🚨 Critical Issues

🔥 Numbered Lists in Code Example (Lines 114-118)
The system prompt example contains numbered lists that should use <Steps> component instead:

1) There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza
2) There are 3 kinds of sides: french fries, garlic bread, and chicken wings.
3) There are 2 kinds of drinks: soda, and water.

Recommended fix:
Since this is within a code block for the AI prompt, keep the numbered format as it's part of the actual prompt content that users need to copy.

⚠️ Writing Style Issues

📝 Grammar Error (Line 50)

• "it's voice pipeline" should be "its voice pipeline" (possessive, not contraction)

📝 Passive Voice (Lines 65, 161)

• "It is most ideal that we set keys" → "Set keys for vendors you intend to use"
• "We will be using Deepgram" → "Use Deepgram for speech-to-text"

📝 Hyphenation Issues

• "signed-up" should be "signed up" (lines 2, 3)
• "log-in" should be "log in" as verb, "login" as noun (lines 2, 9, 21)
• "pick-up" should be "pick up" (line 78)

💡 Improvements & Suggestions

✨ Streamline Instructions (Line 27)

• "For our example we will start from a blank slate so choose" → "Choose the Blank Template option"

✨ Better Link Context (Line 103)

• The OpenAI docs link is good, but consider adding more context about what readers will find there

🎯 Consistency Issues

• Mixed use of "we're going to" vs "we will" - choose one style consistently
• Some sentences end with periods in code comments, others don't

✅ Things Done Well

🚀 Excellent MDX Component Usage

• Perfect use of <AccordionGroup> and nested <Accordion> components
• Great use of <Frame> components with descriptive captions
• Proper callout components (<Info>, <Note>, <Warning>)

🎉 Strong Structure & Flow

• Logical progression from signup → assistant creation → configuration
• Clear section breaks and hierarchy
• Good use of visual aids with screenshots

✅ User-Focused Content

• Explains the "why" before the "how"
• Provides concrete examples (pizza ordering scenario)
• Includes helpful context about cost & latency projections

🧩 Component Suggestions

💡 Consider Adding:

• A <Check> callout at the end of each major section to confirm completion
• <Tip> callouts for advanced users who want to customize further

Overall, this is a well-structured tutorial with excellent use of MDX components! The main fixes needed are grammar corrections and some style consistency improvements. The content flow and instructional design are strong. 🚀

---

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

Looking at your appointment scheduling workflow documentation, here's my review:

🎉 What's Working Well

✅ Excellent structure - Clear progression from overview to implementation
✅ Great use of Steps components - Properly using <Steps> instead of numbered lists
✅ Comprehensive scenario - Tony's Barbershop example is relatable and practical
✅ Good video integration - Visual aids enhance understanding
✅ Proper front matter - Title and subtitle follow guidelines

🚨 Major Issues to Fix

🔥 Missing subtitle prefix - Your subtitle should begin with "Learn to..." per style guidelines:

subtitle: Learn to build an AI receptionist workflow that schedules, reschedules, and cancels appointments using Vapi workflows.

🔥 Inconsistent node type terminology - You switch between "Conversation node", "Tool node", etc. without clear explanation of what these mean. Define node types early.

⚠️ Minor Issues & Improvements

🤔 Long code blocks need context - Some prompts and configurations are quite long without explaining the key concepts first

🤔 Missing error handling explanation - While you show global error nodes, you don't explain when/why they trigger

📝 Passive voice instances:

• "We will be creating" → "Create an appointment scheduling workflow"
• "You'll start with" → "Start with a default template"

💡 Suggestions & Ideas

✨ Add outcome callout - Consider adding a <Check> component showing what users will achieve:

<Check>
After completing this guide, you'll have a fully automated appointment system that handles booking, rescheduling, and cancellations 24/7.
</Check>

✨ Break up dense sections - Section 3 (Build the Workflow) is quite long. Consider splitting into subsections or using tabs for different appointment types.

🧩 Consider using Tabs for different node configurations:

<Tabs>
  <Tab title="Schedule Appointment">
    [Schedule node config]
  </Tab>
  <Tab title="Reschedule Appointment">
    [Reschedule node config]
  </Tab>
</Tabs>

🎯 Specific Improvements

1. Add node type definitions early - Explain what Conversation, Tool, and Transfer nodes do before using them

2. Simplify complex prompts - Some prompts are 4-5 lines. Break into key points or add explanations

3. Add troubleshooting section - Common issues users might encounter with workflow logic

4. Consider adding a workflow diagram - Visual representation of the branching logic would be helpful

Overall, this is a solid, comprehensive guide! The main fixes needed are the subtitle prefix and better explanation of workflow concepts upfront. The content depth and practical examples are excellent. 🚀

---

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

Looking at your clinic triage and scheduling workflow documentation, this is an excellent example of a comprehensive medical workflow! 🎉 The structure is well-organized and follows most of the documentation guidelines. Here's my detailed review:

✅ Things Done Well

Strong Structure: The logical flow from overview → prerequisites → step-by-step implementation is perfect for task-oriented documentation.

Comprehensive Coverage: You've covered all the essential components - knowledge base setup, tools creation, workflow building, and real-world integration considerations.

Medical Context: The healthcare-specific scenarios and HIPAA compliance considerations show excellent domain awareness.

Visual Learning: Great use of video components to demonstrate key concepts.

🔥 Major Issues to Fix

Critical MDX Component Issue: Throughout the document, you're using numbered lists (1., 2., 3.) when you should be using the <Steps> component. This violates a core MDX guideline.

❌ Current (incorrect):

## 1. Create a Knowledge Base
## 2. Create Required Tools  
## 3. Create a Workflow

✅ Should be:

<Steps>
  <Step title="Create a Knowledge Base">
    Content here...
  </Step>
  <Step title="Create Required Tools">
    Content here...
  </Step>
  <Step title="Create a Workflow">
    Content here...
  </Step>
</Steps>

⚠️ Minor Issues to Address

Title Capitalization: Your title follows the wrong pattern.

• Current: "Clinic triage and scheduling workflow"
• Should be: "Clinic triage and scheduling workflow" ✅ (actually this one is correct)

Subtitle Enhancement: Consider starting with "Learn to..."

• Current: "Build an AI medical workflow..."
• Consider: "Learn to build an AI medical workflow that handles patient triage, scheduling, and emergency routing using Vapi workflows."

💡 Content Suggestions

Emergency Flow Clarity: The emergency detection logic could be clearer. Consider adding a specific callout box explaining when the global emergency node triggers.

Tool Configuration: The tool setup section jumps between placeholder APIs and real system integration. Consider separating the "getting started" tools from production integration more clearly.

📝 Writing Style Improvements

Active Voice: Most of your writing is good, but watch for a few passive constructions:

• "We will be creating" → "Create"
• "I'll need to verify" → "Let me verify"

Consistency: You switch between "you" and "we" - stick with "you" throughout.

🧩 MDX Component Enhancements

Consider adding these components:

Emergency Protocol Callout:

<Warning>
**Emergency Protocol**: If any life-threatening symptoms are detected, the workflow immediately routes to emergency services.
</Warning>

Integration Tips:

<Tip>
Start with the JSONPlaceholder examples, then gradually replace with your EHR system endpoints.
</Tip>

🎯 Specific Action Items

1. Replace all numbered section headers with a single <Steps> component
2. Add emergency protocol callouts in the appropriate sections
3. Clarify the global emergency node trigger conditions
4. Consider adding tabs for different EHR system integrations
5. Add completion indicators for each major section

🚀 Overall Assessment

This is solid, comprehensive documentation that demonstrates deep understanding of both Vapi workflows and healthcare requirements. The main fix needed is converting those numbered sections to the proper <Steps> component - once that's done, this will be an excellent example guide!

The medical context, safety considerations, and real-world integration guidance make this particularly valuable for healthcare developers. Great work! 🏥✨

---

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

🎯 Specific Recommendations

1. 📝 Minor Writing Fixes

Change: "We will be creating an order management workflow"
To: "Create an order management workflow for TechGear Online"

Change: "Note the file IDs. We'll need them later"
To: "Note the file IDs for later use in tool creation"

2. 🧩 Component Enhancement

Consider upgrading this Note to a Warning:

<Warning>
This example uses JSONPlaceholder for demonstration. Replace with your actual e-commerce API endpoints in production.
</Warning>

3. 💡 Structure Suggestion

Break down the massive "Build the Workflow" section into smaller, digestible sections:

• Initial Setup (greeting, identification)
• Inquiry Routing
• Order Management Flow
• Return Processing Flow
• Resolution & Escalation

🚀 Overall Assessment

This is excellent documentation that demonstrates:

• ✅ Perfect use of Steps component
• ✅ Comprehensive real-world guidance
• ✅ Good component usage
• ✅ Clear task-oriented structure
• ✅ Practical code examples

Score: 8.5/10 - Just needs minor writing style tweaks and could benefit from better section organization for the complex workflow building section.

Great work on creating a thorough, practical guide! 🎉

---

📄 fern/workflows/overview.mdx

Documentation Review: Workflows Overview 📝

Overall Assessment ✅

This is a well-structured workflows overview that effectively introduces the visual builder concept. The documentation does a good job explaining complex workflow functionality in an accessible way.

Things Done Well 🎉

Structure & Organization ✅

• Clear progression from introduction → key benefits → structure → node types → edges → best practices
• Good use of MDX components (<Frame>, <Warning>)
• Excellent "Next steps" section with descriptive links

Content Quality ✅

• Comprehensive coverage of all node types with practical examples
• Helpful code snippets for different condition types
• Strong best practices section organized by workflow stage

Visual Elements ✅

• Appropriate use of <Frame> components for screenshots
• Good image placement to support explanations

Issues That Need Fixing 🚨

Grammar & Language Issues 📝

• Line 31: "Workflows consists of node and edges" → "Workflows consist of nodes and edges"
• Line 33: "type of note" → "type of node"
• Line 56: "heavily depend" → "heavily depends"
• Line 60: Missing comma: "escalation purposes e.g." → "escalation purposes, e.g.,"

Consistency Issues ⚠️

• Line 70: Inconsistent bullet style - switches from dashes to bullets mid-section
• Should use consistent dashes throughout for bullet lists

Missing Context 🤔

• Line 82: References "body UI builder" without prior explanation
• Could benefit from brief context about what JSON Schema formatting means

Suggestions for Improvement 💡

Enhanced Scannability ✨

• Consider adding a brief intro paragraph to "Node Types and Configuration" section
• The section could benefit from a summary table of node types and their purposes

Link Improvements 🎯

• Line 82: Link text "JSON Schema" could be more descriptive like "JSON Schema formatting guide"
• Line 92: "transfer plan" link is good descriptive text ✅

Content Enhancement 💡

• Consider adding a brief example of when to use each node type
• The "Common Use Patterns" section could include simple workflow diagrams

Technical Accuracy ✅

The technical content appears accurate and well-researched. The explanations of different node types, configuration options, and edge conditions are comprehensive and practical.

Action Items 🎯

1. Fix grammar errors (lines 31, 33, 56, 60)
2. Standardize bullet formatting (line 70)
3. Add context for "body UI builder" (line 82)
4. Consider adding node type summary table

This documentation provides a solid foundation for understanding Workflows. With these minor fixes, it will be even more effective at helping users get started with the visual builder! 🚀

---

📄 fern/docs.yml

🎉 Great documentation structure! Your YAML configuration looks well-organized and professional. Here's my review:

✅ What's Working Well

🚀 Excellent organization: Your navigation structure is logical and follows a clear hierarchy from getting started to advanced topics.

📝 Clear naming: Page titles follow good capitalization (first word only) and are descriptive.

🎯 User journey flow: The progression from "Get started" → "Assistant customization" → "Best practices" makes sense for users.

🧩 Proper icons: FontAwesome icons are consistently used and meaningful.

⚠️ Minor Issues to Address

📝 Typo spotted (line 266):

• "Twillio" should be "Twilio" (the correct company name)

🤔 Inconsistent section labeling (line 429):

• "Transcribers (Text-to-speech)" should be "Transcribers (Speech-to-text)" - transcribers convert speech TO text, not text to speech.

💡 Navigation optimization suggestion:

• The "Resources" section is quite long. Consider if some subsections could be promoted to top-level or reorganized for better scannability.

🎯 Specific Improvements

1. Line 266: Change Twillio to Twilio
2. Line 429: Change Transcribers (Text-to-speech) to Transcribers (Speech-to-text)

🚀 Overall Assessment

This is a solid documentation configuration! The structure supports excellent user experience with logical grouping, clear hierarchies, and comprehensive coverage. The redirects section shows good maintenance of legacy URLs. The only issues are minor typos that are easy fixes.

Your navigation structure particularly excels at progressive disclosure - users start with basics and can dive deeper as needed. The collapsed sections help keep the interface clean while providing access to comprehensive information.

---

📄 fern/workflows/examples/lead-qualification.mdx

Looking at your lead qualification workflow documentation, here's my review:

✅ What's Working Well

🚀 Excellent workflow complexity - You've built a sophisticated sales workflow with proper branching logic, global objection handling, and CRM integration

🎉 Great use of components - Perfect implementation throughout instead of numbered lists

✅ Strong technical integration - Good examples of real CRM/calendar APIs and practical implementation guidance

🎯 Clear value proposition - The TechFlow Solutions scenario makes the workflow tangible and relatable

🚨 Critical Issues to Fix

🔥 Broken file references - The spreadsheet downloads reference outbound-sales directory but should be lead-qualification:

<!-- Current (broken) -->
<Download src="../../static/spreadsheets/outbound-sales/leads.csv">

<!-- Should be -->
<Download src="../../static/spreadsheets/lead-qualification/leads.csv">

🔥 Front matter mismatch - The slug and file references don't align with the renamed example

⚠️ Minor Improvements Needed

📝 Subtitle clarity - Consider: "Learn to build an AI sales workflow that qualifies leads and schedules appointments"

🤔 Long paragraphs - Break down some of the longer prompt examples in the workflow configuration steps

💡 Missing context - The curl example could use a brief explanation of what it does

🧩 MDX Component Suggestions

✨ Consider adding a callout about testing with real phone numbers:

<Tip>
Start with test phone numbers before deploying to real prospects. Use a small list to validate your workflow logic.
</Tip>

⚠️ Add a about API rate limits:

<Warning>
Be mindful of CRM API rate limits when processing large lead lists. Implement proper error handling and retry logic.
</Warning>

🎯 Quick Fixes Needed

1. File paths: Update all outbound-sales references to lead-qualification
2. Add missing context: Brief explanation before the curl command
3. Break up prompts: Split longer prompt examples into shorter, scannable chunks

Overall, this is a comprehensive and well-structured workflow guide! The main issue is the file path references that need updating to match the renamed example. The technical content and workflow design are excellent. 🚀

---

📖 Style Guidelines | Thanks for contributing! 🙏✨

[github-actions]

📝✨ Documentation Review by Claude 🤖

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

📄 fern/examples/voice-widget.mdx

Looking at your voice widget documentation, here's my review:

✅ Overall Strengths

• Great use of <Steps> component (perfect! 🎉)
• Clear, practical code examples throughout
• Good logical flow from setup to customization
• Consistent terminology and formatting

🚨 Major Issues to Fix

Title Capitalization:

• Should be "Web snippet" not "Web Snippet" (only first word capitalized)

Subtitle Length:

• Current subtitle is too long and promotional
• Suggestion: "Learn to integrate Vapi's voice widget into your website"

⚠️ Minor Issues & Improvements

Step Titles Need Consistency:

• "Insert the Widget Snippet" → "Insert the widget snippet"
• "Generate Your Assistant" → "Generate your assistant"
• "Modify the Button" → "Modify the button"
• "Add Functionality to Vapi Instance" → "Add functionality to Vapi instance"

Writing Style 📝:

• "From your Vapi dashboard, create an assistant" → "Create an assistant in your Vapi dashboard"
• "Modify the buttonConfig object to align with your website's style" → "Configure the buttonConfig object to match your website's style"

💡 Content Suggestions

Missing Context:

• Step 1 should explain why to place the script before </body>
• Step 2 could mention when to use assistant ID vs inline config

Code Comments:

• The comments in Step 4 could be more descriptive about what each event does

✨ Enhancement Ideas

Add a Tip callout after Step 1:

<Tip>
Place the script before the closing `</body>` tag to ensure the page loads completely before initializing the widget.
</Tip>

Consider adding a Note about API keys:

<Note>
Use your **public** API key here, not your private key. Find it in the Vapi Dashboard under API Keys.
</Note>

🎯 Specific Fixes Needed

1. Update front matter title and subtitle
2. Fix step title capitalization
3. Add brief explanations for why certain placements/configurations are recommended
4. Consider breaking up the long code block in Step 3 with explanatory text

The structure and use of MDX components is excellent! 🚀 Just needs these style and clarity improvements to be perfect.

---

📄 fern/quickstart/dashboard.mdx

Documentation Review for fern/quickstart/dashboard.mdx

Great work on this quickstart guide! 🎉 The structure is solid and follows most of the style guidelines. Here's my detailed feedback:

✅ Things Done Well

🚀 Perfect use of <Steps> component - You correctly used the Steps component instead of numbered lists throughout
🎯 Clear structure - Logical flow from overview to hands-on implementation
✅ Good front matter - Title and subtitle follow the guidelines
🎉 Active voice - Most instructions use proper active voice ("Set the first message", "Select your preferred provider")
✨ Concrete examples - Great code snippets for first message and system prompt

🔥 Major Issues to Fix

🚨 Bold formatting inconsistency: The overview uses ***assistants*** (triple asterisks) instead of standard **assistants** (double asterisks)

🚨 Missing context for code examples: The system prompt is truncated with "..." - users need the complete example or clear indication of where to find the full prompt

⚠️ Minor Issues & Improvements

📝 Tone consistency: "Just like with the transcriber, you can plug in any provider!" - while friendly, this feels slightly informal for the established tone

🤔 Link text: Consider making "dashboard.vapi.ai" more descriptive, like "the Vapi dashboard"

⚠️ Mixed instruction format: Step 1 in outbound calls uses numbered list format within the step description - consider restructuring for consistency

💡 Suggestions & Ideas

✨ Add outcome focus: Consider adding a brief "What you'll have" section at the end summarizing what users accomplished

🧩 Callout opportunity: The truncated system prompt could use a <Note> callout explaining where to find the complete example

🎯 Scannability: The nested Steps work well, but consider if some of the deeper nesting could be simplified

🎯 Specific Improvements

Fix the bold formatting:

- Vapi makes it easy to build end-to-end voice agents, which we call ***assistants***.
+ Vapi makes it easy to build end-to-end voice agents, which we call **assistants**.

Complete the system prompt example or add context:

You are Alex, a customer service voice assistant for TechSolutions...
- ...
+ [Continue with full prompt or add: "View the complete system prompt in the dashboard template"]

Improve the outbound call step:

<Step title="Set your phone number and assistant">
-   1. Fill out <strong>your own phone number</strong> as the number to dial.
-   2. Set the assistant that will be making the call
+   Fill out **your own phone number** as the number to dial, then set the assistant that will be making the call.

Overall, this is a well-structured quickstart that effectively guides users through their first Vapi assistant! 🚀 The main fixes are formatting consistency and completing the code examples.

---

📄 fern/snippets/quickstart/dashboard/assistant-setup-inbound.mdx

Looking at this documentation snippet, here's my review:

✅ Things Done Well

🎉 Great use of nested accordions - The hierarchical structure with <AccordionGroup> and nested <Accordion> components makes this very scannable and organized

🚀 Excellent visual support - Good use of <Frame> components with descriptive captions for all screenshots

✅ Consistent terminology - Terms like "assistant," "provider keys," and "voice pipeline" are used consistently throughout

✅ Proper callout usage - Good mix of <Info>, <Note>, and <Warning> callouts that add value

🚨 Major Issues That Need Fixing

🔥 Numbered lists should use Steps component - I found several numbered lists that should be converted:

In the "Set the System Prompt" section:

1) There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza
2) There are 3 kinds of sides: french fries, garlic bread, and chicken wings.  
3) There are 2 kinds of drinks: soda, and water.

Should be:

<Steps>
  <Step title="Pizza options">
    There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza (often called "veggie" pizza).
  </Step>
  <Step title="Sides options">
    There are 3 kinds of sides: french fries, garlic bread, and chicken wings.
  </Step>
  <Step title="Drink options">
    There are 2 kinds of drinks: soda, and water. (if a customer asks for a brand name like "coca cola", just let them know that we only offer "soda")
  </Step>
</Steps>

⚠️ Minor Issues & Improvements

📝 Link text improvements:

• [dashboard.vapi.ai](https://dashboard.vapi.ai) → [Vapi dashboard](https://dashboard.vapi.ai)
• [dashboard.vapi.ai/keys](https://dashboard.vapi.ai/keys) → [provider keys page](https://dashboard.vapi.ai/keys)

🤔 Tone inconsistencies - Mix of casual ("you're going to need") and formal language. Consider standardizing to: "you need an account"

💡 Missing front matter - This snippet appears to lack title/subtitle front matter for proper context

🎯 Specific Writing Improvements

📝 Passive voice instances:

• "you will then find yourself" → "you'll see"
• "you will see a pop-up modal" → "a modal appears"
• "You will then be able to name" → "Name your assistant"

📝 Brevity opportunities:

• "If you haven't already signed-up, you're going to need an account before you can use the web dashboard" → "Sign up for an account to access the dashboard"

✨ Overall Assessment

This is well-structured documentation with good visual hierarchy and helpful screenshots. The main improvement needed is converting those numbered lists to the proper <Steps> component, plus some minor writing style refinements. The nested accordion approach works really well for this type of setup guide! 🚀

---

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

Documentation Review ✅ 🎉

This is an excellent appointment scheduling workflow guide! Here's my comprehensive review:

Strengths 🚀

✅ Perfect MDX Component Usage: Uses <Steps> components throughout instead of numbered lists - exactly what we want to see!

✅ Clear Structure: The guide follows a logical flow from setup to testing with well-organized sections

✅ Concrete Example: Using "Tony's Barbershop" makes the guide relatable and easy to follow

✅ Outcome Focus: Each section clearly supports user success in building a working appointment system

✅ Good Use of Code Blocks: Configuration examples are clearly presented in code blocks

Style Feedback 🎯

Minor Improvements

⚠️ Front Matter: The title follows guidelines perfectly, but consider making the subtitle more concise:

• Current: "Build an AI receptionist workflow that schedules, reschedules, and cancels appointments using Vapi workflows."
• Suggested: "Learn to build an AI receptionist that handles appointment booking with branching logic"

💡 Passive Voice in a Few Places: Most writing is active voice, but a couple instances could be improved:

• Line 26: "We will be creating" → "Create an appointment scheduling workflow"
• Line 85: "You'll start" → "Start with a default template"

Writing Style

✅ Active Voice: Generally excellent use of active voice throughout
✅ Present Tense: Correctly uses present tense for instructions
✅ Second Person: Proper use of "you" throughout
✅ Intent Before Action: Good at explaining why before how

Content Organization

✅ Scannability: Excellent use of headings and visual organization
✅ Brevity: Steps are appropriately sized and digestible
✅ Task Orientation: Logical progression from setup to testing

Technical Details

✅ Code Examples: Good use of code blocks for configuration
✅ Variables and Conditions: Clear explanation of workflow logic
✅ Error Handling: Includes global error handling - excellent practice

Minor Suggestions 💡

1. Line 441: "Just like that" could be more formal - consider "You've successfully built"

2. Consistency: The guide does well maintaining consistent terminology for "nodes," "tools," and "workflows"

3. Links: All links use descriptive text (avoiding "click here") ✅

Overall Assessment 🎉

This is a high-quality documentation example that effectively demonstrates:

• Complex workflow building with branching logic
• Real-world business scenario implementation
• Proper use of Vapi's workflow components
• Clear step-by-step instructions

The guide successfully teaches readers to build a sophisticated appointment system while following documentation best practices. Great work! 🚀

---

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

(no content)

---

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

(no content)

---

📄 fern/workflows/overview.mdx

🎯 Specific Recommendations

🔥 High Priority Fixes

1. Grammar: "Workflows is" → "Workflows are"
2. Header level: "Node Types and Configuration" needs ##

✨ Enhancement Suggestions

1. Add context to code examples:

   // Example: Route users who express interest in voice technology
   User wanted to talk about voice agents

2. Consider <Tip> callouts:

   <Tip>
   Extract variables as enums to enable reliable branching between conversation paths.
   </Tip>

3. Break up longer paragraphs in the Introduction and Key Benefits sections

🚀 What's Working Great

• Comprehensive coverage of all node types
• Practical best practices section
• Strong visual support with images
• Clear next steps and resource links
• Professional, task-oriented tone

📊 Overall Assessment

This is a high-quality documentation page that effectively serves developers and low-code builders. With the minor fixes above, it will be an excellent resource for understanding Workflows! 🎉

The document successfully balances comprehensive coverage with practical guidance, making it both a reference and a learning tool.

---

📄 fern/docs.yml

Looking at this YAML configuration file for Fern documentation, this is primarily a configuration file rather than user-facing documentation, so most of the content guidelines don't directly apply. However, I can review it for clarity and best practices:

✅ What's Working Well

🎉 Excellent organization - The navigation structure is logical and well-hierarchical
🚀 Comprehensive coverage - Good breadth of topics from quickstart to advanced features
✅ Consistent naming - File paths and slugs follow clear conventions
🎯 Good use of icons - Font Awesome icons are consistently applied throughout

💡 Minor Improvements

⚠️ Title consistency - Some titles use different capitalization patterns:

• "Get started" vs "Assistant customization"
• "Phone numbers" vs "Phone Number Hooks"
• Consider standardizing to sentence case throughout

🤔 Navigation depth - Some sections are quite deeply nested (4-5 levels). Consider if any could be flattened for better user navigation.

📝 Redirect clarity - The redirects section is extensive and well-maintained, which is great for SEO and user experience.

🧩 Technical Notes

✨ Good MDX setup - The experimental MDX components configuration looks solid
🎯 Analytics integration - Both PostHog and GA4 are properly configured
✅ Brand consistency - Logo, colors, and styling are well-defined

Overall Assessment

This is a well-structured documentation configuration file that shows thoughtful organization. The navigation hierarchy makes sense for a complex API/platform like Vapi, and the comprehensive redirect list shows good maintenance practices.

The file serves its purpose well as a configuration file - it's more about technical setup than user-facing content, so the writing guidelines are less applicable here.

---

📄 fern/workflows/examples/lead-qualification.mdx

Looking at your lead qualification workflow documentation, I found several areas that need attention. Here's my detailed review:

🚨 Critical Issues

Numbered Lists → Steps Component
You have multiple numbered lists that should use the <Steps> component:

In section 1 (Create a Knowledge Base), convert:

1. Download the spreadsheets
2. Navigate to the Files section  
3. Upload the spreadsheets

To:

<Steps>
  <Step title="Download the spreadsheets">
    [content]
  </Step>
  <Step title="Navigate to the Files section">
    [content]
  </Step>
  <Step title="Upload the spreadsheets">
    [content]
  </Step>
</Steps>

⚠️ Writing Style Issues

📝 Passive Voice - Convert to Active

• "We will be creating" → "Create an outbound sales workflow"
• "can you tell me" → "tell me"

📝 Inconsistent Terminology

• Mix of "prospect" and "lead" - choose one and stick with it
• "conversation node" vs "Conversation Node" - be consistent with capitalization

🧩 MDX Component Improvements

Missing Callouts
Add appropriate callouts for important information:

<Warning>
Replace JSONPlaceholder URLs with your actual CRM endpoints before production use.
</Warning>

<Tip>
Test your workflow with internal phone numbers before calling real prospects.
</Tip>

Code Block Languages
Add language identifiers to your code blocks:

```bash
curl -X POST https://api.vapi.ai/call \

{
  "phoneNumberId": "your-phone-number-id"
}

💡 Content Suggestions

🎯 Add Prerequisites Section
Your prerequisites are too generic. Add specific requirements:

## Prerequisites

* A [Vapi account](https://dashboard.vapi.ai/) with outbound calling enabled
* CRM system with API access (Salesforce, HubSpot, or Pipedrive)
* Calendar system for appointment scheduling (Google Calendar or Calendly)
* Lead database with contact information and qualifying data

🎯 Missing Context for Code Examples
Your curl example needs more explanation:

<Note>
This initiates an outbound call to the specified number using your configured assistant and workflow.
</Note>

✅ Things Done Well

🎉 Excellent workflow complexity - You've created a sophisticated branching logic system
🚀 Comprehensive scenario - The TechFlow Solutions example provides good context
✨ Good tool integration - Shows how to connect multiple systems effectively

🎯 Specific Improvements Needed

1. Front Matter: Add sidebarTitle for better navigation
2. Link Text: Replace generic "API" links with descriptive text like "Salesforce REST API documentation"
3. Scannability: Break up the long Step 4 into smaller subsections
4. Outcome Focus: Add a "What you'll accomplish" section at the top

📝 Quick Fixes

• Remove "just" from "just 2 minutes" (unnecessary filler)
• Change "I hope I'm catching you at a good time" to "I hope this is a good time"
• Use consistent button styling for all download links

Overall, this is a comprehensive guide that shows deep understanding of sales workflows! With these improvements, it will be much more scannable and user-friendly. 🚀

---

📖 Style Guidelines | Thanks for contributing! 🙏✨

[github-actions]

🌿 Preview your docs: https://vapi-preview-e69a5795-5a38-458e-9256-23fb6b223ce6.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/examples/voice-widget.mdx

Documentation Review: Voice Widget Guide

Great job on using the <Steps> component properly! ✅ This is exactly how sequential instructions should be formatted. Here's my detailed review:

✅ What's Working Well

• 🚀 Perfect use of <Steps> component - Sequential instructions are properly structured
• 🎯 Clear, actionable step titles that tell users exactly what they'll accomplish
• 💡 Comprehensive code examples with helpful inline comments
• 📝 Good use of backticks for code elements like buttonConfig and vapiInstance

🤔 Areas for Improvement

Title & Subtitle Issues

⚠️ Title capitalization: "Web Snippet" should be "Web snippet" (only first word capitalized unless proper noun)

🎯 Subtitle could be more action-oriented: Consider changing from:

"Easily integrate the Vapi Voice Widget into your website for enhanced user interaction."

To something like:

"Learn to integrate the Vapi Voice Widget into your website for voice-enabled user interactions."

Writing Style

📝 Opening paragraph is wordy: The first paragraph could be more direct:

Current:

"Improve your website's user interaction with the Vapi Voice Widget. This robust tool enables your visitors to engage with a voice assistant for support and interaction, offering a smooth and contemporary way to connect with your services."

Suggested:

"Add voice interactions to your website with the Vapi Voice Widget. Let visitors engage with an AI assistant for support using natural conversation."

Content Structure

💡 Step 2 needs better context: "Generate Your Assistant" could explain why users need an assistant ID before showing how to get one.

⚠️ Step 4 is unclear: "Add Functionality to Vapi Instance" doesn't clearly explain the purpose. Consider renaming to "Listen for events" or "Handle widget events."

Technical Issues

🔥 Missing context in examples: The code examples need brief explanations of what they accomplish before diving into the code.

🎯 UI Customization section is too bare: The CSS class list needs context about how/when to use them.

💡 Specific Suggestions

1. Add context before code blocks: Explain what each code example accomplishes
2. Break up the button config example: It's quite long - consider using <Tabs> for different button states
3. Add a <Tip> callout about where to find the assistant ID in the dashboard
4. Include expected outcomes for each step so users know they're on track

🚀 Overall Assessment

This is a solid technical guide that correctly uses MDX components. With some writing polish and better context-setting, it will be excellent. The structure is sound and the examples are comprehensive!

---

📄 fern/quickstart/dashboard.mdx

Looking at your dashboard quickstart documentation, I have some feedback to help improve it! Overall, this is a well-structured guide that follows many of the best practices. Here's my review:

✅ Things Done Well

🎉 Excellent use of Steps components - You're correctly using <Steps> instead of numbered lists throughout
🚀 Clear task orientation - The flow from creating to configuring to testing is logical
✅ Good use of Frames with captions - Visual elements are well-documented
🎯 Active voice and present tense - "Create an assistant" not "You will create"
✅ Proper front matter - Title and subtitle follow guidelines

🤔 Minor Issues & Improvements

⚠️ Subtitle formatting: Your subtitle should start with "Learn to..." for guides:

subtitle: Learn to build a voice agent in under 5 minutes.

Should be:

subtitle: Learn to build a voice agent in under 5 minutes

(Remove the period)

📝 Tone consistency: In the outbound call section, you use "1. Fill out" and "2. Set" - this feels like a numbered list disguised as text. Consider restructuring:

Instead of:

1. Fill out **your own phone number** as the number to dial.
2. Set the assistant that will be making the call

Use:

Fill out **your own phone number** as the number to dial and set the assistant that will be making the call.

💡 Suggestions & Ideas

✨ Add context before actions: In some places, you could explain why before how:

For example, before "Set the first message", add: "The first message creates the initial impression and sets expectations for the conversation."

🧩 Consider a Note callout for the assistant components explanation:

<Note>
Each assistant has three components: Speech-to-text (STT), Language model (LLM) and Text-to-speech (TTS). Vapi gives you full control over each, with dozens of providers and models to choose from.
</Note>

🎯 Link text improvement: "A Vapi account" could be more descriptive:

- [Sign up for a Vapi account](https://dashboard.vapi.ai)

🔥 One Technical Issue

🚨 Inconsistent nested Steps: You have <Steps> inside <Steps> which might cause rendering issues. Consider flattening the structure or using different components for sub-tasks.

Overall Assessment

This is a solid quickstart guide that effectively gets users from zero to a working voice assistant! The structure is logical, the writing is clear, and you're using MDX components appropriately. With these minor tweaks, it'll be even better! 🚀

---

📄 fern/snippets/quickstart/dashboard/assistant-setup-inbound.mdx

Looking at this documentation file, here's my review against the guidelines:

✅ Things Done Well

🎉 Great use of MDX components: The accordion structure works perfectly for this complex setup process
🚀 Excellent scannability: Clear headings and logical flow through the assistant setup
✅ Good use of callouts: , , and components are used appropriately
🎯 Task-oriented structure: Each accordion focuses on a specific setup step
✅ Concrete examples: Real prompts and configuration examples provided

🚨 Major Issues That Need Fixing

🔥 Numbered lists instead of Steps component: The system prompt section uses a numbered list (1, 2, 3) that should be converted to the <Steps> component:

Instead of:

1) There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza
2) There are 3 kinds of sides: french fries, garlic bread, and chicken wings.  
3) There are 2 kinds of drinks: soda, and water.

Use:

<Steps>
  <Step title="Pizza options">
    There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza (often called "veggie" pizza).
  </Step>
  <Step title="Side options">
    There are 3 kinds of sides: french fries, garlic bread, and chicken wings.
  </Step>
  <Step title="Drink options">
    There are 2 kinds of drinks: soda, and water. (if a customer asks for a brand name like "coca cola", just let them know that we only offer "soda")
  </Step>
</Steps>

⚠️ Minor Issues & Improvements

📝 Passive voice usage:

• "assistants can optionally be configured" → "you can optionally configure assistants"
• "This first message will be spoken" → "Your assistant speaks this first message"

🤔 Long paragraphs: Some sections have dense paragraphs that could be broken up for better readability, especially in the system prompt explanation.

💡 Link text improvements:

• "visit dashboard.vapi.ai" could be "visit the Vapi dashboard"

📝 Writing Style Suggestions

✨ Convert to active voice consistently:

• "The transcriber is what turns user speech" → "The transcriber turns user speech"
• "This process is called" → "This process converts"

🎯 Tighten some explanations: The provider key explanations could be more concise and direct.

Overall Assessment

This is a solid documentation piece with excellent structure and helpful examples! The main fix needed is converting that numbered list to the <Steps> component, plus some minor voice and clarity improvements. The accordion organization works really well for this complex setup process. 🚀

---

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

Looking at this appointment scheduling workflow documentation, here's my review:

✅ What's Working Well

🎉 Excellent structure: The flow from overview → prerequisites → step-by-step implementation is logical and easy to follow.

✅ Great use of Steps component: You correctly use <Steps> instead of numbered lists throughout - this is exactly right!

🚀 Comprehensive coverage: The workflow covers all the major appointment scenarios (schedule, reschedule, cancel) with proper branching logic.

✅ Good video integration: Videos are properly embedded to support the written instructions.

🤔 Areas for Improvement

Writing Style Issues 📝

Passive voice in several places:

• "We will be creating an appointment scheduling workflow" → "You'll create an appointment scheduling workflow"
• "You'll start with a default template that includes a 'Call Start' node" → "Start with the default template that includes a 'Call Start' node"

Some jargon without explanation:

• "Global nodes" needs a brief explanation when first mentioned
• "Extract Variables" could use context about what this accomplishes

Structure & Clarity 🎯

⚠️ Long code blocks: Some prompt examples are quite lengthy. Consider breaking them into shorter, more scannable sections.

💡 Missing context: The customer lookup tool and calendar tools are referenced but not explained. Add a brief note about setting these up first.

Front matter suggestion:

• Title could be more task-oriented: "Build an appointment scheduling workflow"

Content Organization 🧩

🤔 Step 1 feels disconnected: The knowledge base creation could be better integrated - explain why these specific files are needed for the workflow.

⚠️ Prerequisites section: Could mention the calendar integration setup since it's referenced throughout.

🎯 Specific Improvements

1. Add brief explanations for technical terms like "global nodes" and "extract variables"
2. Break up long prompts into bullet points or shorter paragraphs
3. Add context about prerequisite tools (customer lookup, calendar integration)
4. Convert remaining passive voice to active voice throughout

Overall Assessment

This is solid workflow documentation that follows most best practices well! The main improvements needed are writing style consistency and adding more context for technical concepts. The structure and use of MDX components is excellent. 🚀

---

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

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

🎉 What's Working Well

✅ Excellent use of MDX components - Perfect implementation of <Steps>, <Note>, <Warning>, and <Frame> components throughout
✅ Strong task orientation - Clear logical flow from knowledge base creation through final testing
✅ Comprehensive real-world integration guidance - Great section on EHR systems and HIPAA compliance
✅ Good scannability - Well-structured headings and clear section breaks
✅ Professional medical tone - Appropriate for healthcare context while remaining accessible

🚨 Critical Issues to Fix

Front Matter Problems:

• ❌ Title capitalization: Should be "Clinic triage and scheduling workflow" (only first word capitalized)
• ❌ Missing subtitle prefix: Should start with "Learn to build an AI medical workflow..." for consistency

⚠️ Areas for Improvement

Writing Style:

• 📝 Passive voice in several places:
  • "We will be creating" → "You'll create"
  • "should be created" → "create these tools"
  • "can be used" → "use these APIs"

Content Structure:

• 🤔 Missing outcome focus: The overview explains what you'll build but doesn't clearly state the end result/benefit
• 🎯 Tool creation could be clearer: Consider explaining why each tool is needed before the creation steps

💡 Specific Suggestions

Improve the overview section:

## Overview

Build an AI-powered clinic receptionist that handles patient triage, appointment scheduling, and emergency routing. Your workflow will reduce wait times, ensure appropriate care routing, and maintain 24/7 patient access while following medical protocols.

Fix passive voice examples:

• "I'll need to verify" → "I need to verify"
• "can be scheduled" → "schedule appointments"
• "should be directed" → "direct patients"

Strengthen the Prerequisites section:

• 💡 Add context about why each prerequisite is needed
• 🎯 Consider adding estimated setup time

✨ Enhancement Opportunities

• 🧩 Consider adding a <Tip> callout about testing the emergency routing safely
• 💡 Add a brief explanation of workflow complexity/difficulty level
• 🎯 Include estimated implementation time for teams

🚀 Overall Assessment

This is a comprehensive, well-structured piece that effectively guides users through building a complex medical workflow. The integration guidance and real-world considerations are particularly valuable. With the front matter fixes and passive voice corrections, this will be an excellent resource for healthcare organizations implementing AI workflows.

The technical depth and practical examples make this documentation very actionable - great work on balancing complexity with clarity! 🌟

---

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

Documentation Review for E-commerce Order Management Workflow 📋

Overall, this is a well-structured and comprehensive documentation that follows most of the guidelines effectively! Here's my detailed feedback:

✅ What's Done Well 🎉

Front Matter & Structure:

• ✅ Title follows proper capitalization (only first word)
• ✅ Subtitle is clear and task-oriented
• ✅ Excellent use of <Steps> component throughout
• ✅ Good logical flow from setup to implementation

Content & Style:

• ✅ Uses active voice consistently ("Build", "Create", "Configure")
• ✅ Present tense throughout ("Click", "Add", "Configure")
• ✅ Second person "you" appropriately used
• ✅ Concrete examples with TechGear Online scenario
• ✅ Good use of callouts with <Note> components
• ✅ Descriptive link text (no "click here")

MDX Components:

• ✅ Proper use of <Steps> and <Step> components
• ✅ Good use of <Frame> for the workflow image
• ✅ Appropriate <Note> callouts for important information
• ✅ Video integration with proper styling

🎯 Areas for Improvement

📝 Writing Style Issues

Line 24-26: 🤔 Passive voice detected

We will be creating an order management workflow for TechGear Online

Should be:

Create an order management workflow for TechGear Online

Line 607-608: 🤔 Passive voice

This example uses JSONPlaceholder for demonstration purposes. To integrate with your actual e-commerce systems:

Should be:

This example uses JSONPlaceholder for demonstration. Integrate with your actual e-commerce systems:

🧩 MDX Component Issues

Lines 483-484: 🚨 Major issue - Inconsistent variable extraction format

- Variable: `return_reason`
- Type: `String`
- Description: `Reason for return`
- Verify return policy compliance and item condition

The last line appears to be orphaned content that should be integrated into the description or moved elsewhere.

Line 581: ⚠️ Minor formatting inconsistency

**Workflow**: Select your `TechGear Customer Service Workflow`

Consider making this consistent with other configuration sections by using a colon after the bold text.

💡 Content Enhancement Suggestions

Lines 429, 453, 493: 💡 Could be more specific
The bullet points like "- Add a Tool node that calls your order tracking API with order information" could provide more specific configuration details similar to other steps.

Lines 555, 565: 💡 Missing detail
The bullet points "- Provide solutions, credits, or compensations" and "- Use when customer issue is resolved" could be expanded with specific configuration guidance.

🎯 Specific Improvements

Line 626: ✨ Great closing but could be more action-oriented

Just like that, you've built an e-commerce customer service workflow...

Consider:

You've successfully built an e-commerce customer service workflow...

🚀 Overall Assessment

This documentation is excellent and follows the guidelines well! The main issues are minor writing style adjustments and a few formatting inconsistencies. The use of the <Steps> component is perfect, and the content is comprehensive and practical.

Priority fixes:

1. 🔥 Fix the orphaned content on line 484
2. 📝 Convert passive voice to active voice in a few places
3. 💡 Add more specific configuration details for the incomplete tool nodes

Grade: A- (90/100) - This is high-quality documentation that users will find very helpful! 🎉

---

📄 fern/workflows/overview.mdx

Documentation Review: Workflows Overview

Overall, this is a solid documentation page with good structure and clear content! Here's my detailed feedback:

✅ Strengths

🎉 Front Matter: Perfect title and subtitle formatting
🚀 Visual Structure: Great use of <Frame> components for images
✅ MDX Components: Proper use of <Warning> callout
🎯 Content Organization: Logical flow from overview to specifics
✨ Code Examples: Good use of code blocks for condition examples

🔥 Major Issues

📝 Grammar Errors (Line 31, 33):

• "Workflows consists of nodes and edges"
• "type of nodee" should be "type of node"

⚠️ Minor Issues & Improvements

📝 Inconsistent Spacing (Lines 10, 41, 76, 94, 102, 114, 123):

• Extra leading space before <Frame> tags - should align properly

📝 Writing Style Issues:

• Line 56: "Building reliable... heavily depends" (subject-verb agreement)
• Line 50: "without waiting for the user to say something"
• Line 60: "e.g." should have comma after: "e.g.,"

🤔 Passive Voice (Line 112):

• "Select tools previously created" → "Select tools you previously created"

💡 Suggestions

✨ Consistency: Consider standardizing "HTTP Requests" vs "HTTP requests" (line 82)

🧩 Structure: The "Node Types and Configuration" section could benefit from a brief intro paragraph explaining what you're about to learn

🎯 Scannability: Consider adding brief descriptions under each node type heading before diving into details

📝 Specific Fixes Needed

Line 31: "Workflows consist of nodes and edges"
Line 33: "different type of node"
Line 50: "without waiting for the user"
Line 56: "Building reliable... heavily depends"
Line 60: "escalation purposes, e.g., when"
Line 112: "Select tools you previously created"

Spacing: Remove extra spaces before all <Frame> tags

🚀 Overall Assessment

This documentation effectively explains Workflows with clear explanations, good visual support, and practical examples. The content is well-structured and user-focused. Just fix the grammar issues and spacing inconsistencies, and this will be excellent documentation!

---

📄 fern/docs.yml

Looking at this docs.yml configuration file, I can see this is a Fern documentation configuration rather than a standard documentation page. Let me review it against documentation best practices:

✅ Things Done Well:

• Clear navigation hierarchy with logical grouping and intuitive icons
• Comprehensive redirects that preserve user experience during URL changes
• Consistent naming conventions throughout the navigation structure
• Good use of collapsed sections to prevent overwhelming users
• Proper tab organization separating API reference, documentation, SDKs, and changelog

💡 Suggestions for Improvement:

Navigation Structure

• "Get started" section flows well from quickstart → web call → core concepts
• Assistant customization is well-organized with logical sub-groupings
• Resources section might benefit from being split - it's quite large and mixes different content types

Content Organization

• ✨ Consider moving "Community" up in the hierarchy - it's valuable but buried deep in Resources
• 🎯 The "Legal" section could be moved to footer links instead of main navigation
• 💡 "Security and privacy" might work better as a top-level section given its importance

Link Descriptions

• Most navigation items have clear, descriptive names ✅
• Some could be more action-oriented:
  • "Core models" → "Learn about core models"
  • "Orchestration models" → "Understand orchestration"

User Journey Flow

• 🚀 The quickstart flow is excellent: Dashboard → Web call → Examples
• ⚠️ Consider adding a "Next steps" or "Advanced topics" section to bridge quickstart and customization

Icon Usage

• ✅ Icons are used consistently and meaningfully
• 🎯 Some icons could be more intuitive (fa-light fa-hashtag for C# seems unclear)

🔥 Minor Technical Notes:

• File is well-structured YAML with proper syntax ✅
• Analytics and tracking properly configured ✅
• Custom domain and branding elements in place ✅

This is a well-organized documentation structure that prioritizes user success and clear navigation paths! The main opportunity is in streamlining the Resources section organization.

---

📄 fern/workflows/examples/lead-qualification.mdx

Looking at this lead qualification workflow documentation, here's my review:

Overall Assessment ✅ 🚀

This is a comprehensive, well-structured guide that follows most documentation best practices. The content is clear, actionable, and provides excellent depth for building a complex sales workflow.

What's Working Well 🎉

Structure & Organization ✅

• Excellent logical flow from setup to implementation
• Clear section breaks with proper headings
• Good use of Prerequisites and Overview sections

Technical Content 🚀

• Comprehensive tool setup instructions
• Detailed node configurations with specific prompts
• Realistic branching logic for different prospect scenarios
• Good integration examples for real systems

MDX Components ✅

• Proper use of <Steps> components throughout
• Good <Note> callouts for important information
• Effective use of <Frame> for the workflow image
• Appropriate video embeds

Issues to Address 🚨

Front Matter 🔥

# Current title uses sentence case - should be title case
title: Lead qualification workflow
# Should be:
title: Lead Qualification Workflow

Subtitle Format ⚠️
The subtitle is good but could be more concise:

# Current (95 characters)
subtitle: Build an AI sales workflow that qualifies leads and schedules appointments using Vapi workflows.
# Suggested (shorter, clearer)
subtitle: Learn to build an AI sales workflow that qualifies leads and schedules appointments.

Minor Improvements 💡

Tone Consistency 📝

• Most content uses good active voice
• Consider making some phrases more direct:
  • "We will be creating" → "You'll create"
  • "You'll start with a default template" → "Start with the default template"

Link Text 🎯
Good descriptive links throughout - no "click here" issues found!

Content Organization ✨
The workflow building section is quite long. Consider if any subsections could benefit from better organization, but overall it's manageable.

Suggestions 🧩

Add Success Indicators 💡
Consider adding a brief section about how to measure workflow success (conversion rates, appointment bookings, etc.)

Error Handling 🤔
Maybe mention what happens when API calls fail or tools don't respond as expected.

Quick Fixes Needed 🎯

1. Title capitalization: Change to "Lead Qualification Workflow"
2. Subtitle: Consider adding "Learn to" prefix for consistency with guide format
3. Minor active voice improvements in a few places

Score: 8.5/10 🚀

This is excellent documentation that provides real value to users building complex sales workflows. The technical depth, clear instructions, and practical examples make it very usable. Just needs minor front matter adjustments!

---

📖 Style Guidelines | Thanks for contributing! 🙏✨

[github-actions]

🌿 Preview your docs: https://vapi-preview-76f5e050-b40a-4387-a3f3-c4ffa6c2d2b3.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/examples/voice-widget.mdx

Great work on this documentation! 🎉 The structure is well-organized and you've correctly used the <Steps> component. Here's my detailed review:

✅ Things Done Well

🚀 Excellent use of MDX components - You properly used <Steps> and <Step> components instead of numbered lists
✅ Clear code examples - All code snippets are well-formatted with proper syntax highlighting
✅ Good structure - Logical flow from installation to customization
✅ Task-oriented approach - Steps clearly guide users through the implementation process

🔥 Major Issues to Fix

🚨 Title capitalization (line 2): Change "Web Snippet" to "Web snippet" - only capitalize the first word unless it's a proper noun

🚨 Passive voice (line 10): "This robust tool enables your visitors to engage" should be active voice: "This tool lets your visitors engage"

⚠️ Minor Issues & Improvements

📝 Writing style (line 47): "From your Vapi dashboard, create an assistant" should be "Create an assistant from your Vapi dashboard" for better action-first approach

📝 Inconsistent terminology (lines 77, 85, 91): Use consistent capitalization - either "Pill" or "pill" throughout (currently mixed)

💡 Missing context (line 100): "For instance, you might want to listen to various EventSource" - could be clearer. Consider: "For example, listen to events or send messages programmatically"

🎯 Specific Improvements

📝 Line 22: "Substitute with your Public key from Vapi Dashboard" - should be "Replace with your public key from the Vapi dashboard" (consistency with lowercase)

📝 Lines 136-138: The "Customization" section is quite brief. Consider adding more specific examples or breaking it into subsections.

💡 Enhancement suggestion: Consider adding a <Tip> callout about where to find the assistant ID in the dashboard for new users.

🧩 MDX Component Suggestions

Consider adding:

• A <Note> callout before the first step about prerequisites (API key, assistant setup)
• A <Tip> in the customization section about testing the widget locally

Overall, this is solid documentation! 🎉 The main fixes needed are title capitalization and converting some passive voice to active voice. The structure and use of components is excellent.

---

📄 fern/quickstart/dashboard.mdx

Looking at your dashboard quickstart documentation, here's my review:

Overall Assessment ✅ 🚀

This is a well-structured quickstart guide that follows most best practices! The content is clear, task-oriented, and uses the proper MDX components effectively.

What's Working Well 🎉

• Excellent use of <Steps> components instead of numbered lists
• Clear front matter with appropriate title and subtitle
• Good visual hierarchy with logical heading structure
• Helpful visuals with frames and captions
• Concrete examples like the system prompt and first message
• Task-oriented approach that guides users through the process

Issues to Address 🚨

1. Formatting Issues 📝

• Triple asterisks around "assistants" - Should be **assistants** (bold) instead of ***assistants***
• Numbered list in outbound call section 🔥:

  1. Fill out <strong>your own phone number</strong> as the number to dial.
  2. Set the assistant that will be making the call
  

  Should use <Steps> component instead!

2. Writing Style Issues ⚠️

• Passive voice detected: "which we call assistants" → "called assistants"
• Inconsistent HTML tags: Mix of <strong> and ** - stick to markdown **bold**

Specific Improvements 🎯

Fix the numbered list:

<Step title="Set your phone number and assistant">
  <Steps>
    <Step title="Enter your phone number">
      Fill out **your own phone number** as the number to dial.
    </Step>
    <Step title="Select assistant">
      Set the assistant that will be making the call.
    </Step>
  </Steps>
</Step>

Clean up the bold formatting:

Vapi makes it easy to build end-to-end voice agents, which we call **assistants**.

Minor Suggestions 💡

• Consider adding a brief explanation of what each model type (STT, LLM, TTS) does before diving into configuration
• The tip about hanging up could be moved to a <Note> component for better visibility

Score: 8.5/10 🌟

Great foundation! Just fix the numbered list and formatting issues, and this will be an excellent quickstart guide.

---

📄 fern/snippets/quickstart/dashboard/assistant-setup-inbound.mdx

Looking at this documentation file, here's my review:

✅ What's Working Well

🎉 Excellent use of Accordions - Perfect for organizing the setup flow into digestible chunks
🚀 Great visual support - Screenshots with descriptive captions help users follow along
✅ Consistent MDX components - Proper use of <Frame>, <Info>, <Note>, and <Warning> callouts
🎯 Task-oriented structure - Logical flow from signup → assistant creation → configuration

🚨 Major Issues to Fix

🔥 Numbered lists instead of Steps component - In the "Set the System Prompt" section, you have:

1) There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza
2) There are 3 kinds of sides: french fries, garlic bread, and chicken wings.  
3) There are 2 kinds of drinks: soda, and water.

This should use the <Steps> component instead:

<Steps>
  <Step title="Pizza options">
    There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza (often called "veggie" pizza).
  </Step>
  <Step title="Side options">
    There are 3 kinds of sides: french fries, garlic bread, and chicken wings.
  </Step>
  <Step title="Drink options">
    There are 2 kinds of drinks: soda, and water. (if a customer asks for a brand name like "coca cola", just let them know that we only offer "soda")
  </Step>
</Steps>

⚠️ Minor Issues & Improvements

📝 Inconsistent voice in system prompt - The prompt switches between formal ("Your job is to take the order") and casual ("Be sure to be kind of funny and witty!"). Consider making the tone more consistent.

🤔 Link text could be more descriptive - Instead of "learn more about prompt engineering on the [OpenAI docs]", use "learn more about [prompt engineering best practices]"

💡 Missing front matter - This snippet file should probably have a title and subtitle for context when used elsewhere.

📝 Writing Style Notes

✨ Good active voice usage throughout
🎯 Clear step-by-step progression
✅ Appropriate use of second person ("you will see", "you can copy")

Overall Assessment

This is a solid documentation snippet that effectively guides users through assistant setup. The main fix needed is converting those numbered lists to the Steps component, and minor polish on consistency. Great work on the visual aids and logical flow! 🚀

---

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

I'll review this appointment scheduling workflow documentation against the guidelines. Overall, this is a well-structured tutorial with good use of MDX components! Here's my feedback:

✅ Things Done Well

🎉 Excellent use of <Steps> component - You correctly used this throughout instead of numbered lists
✅ Great MDX component usage - Good use of <Frame>, <video>, and download buttons
🚀 Clear task-oriented structure - Logical progression from setup to final workflow
✅ Active voice and present tense - "Build an AI-powered workflow" not "You will build"
🎯 Good concrete examples - Specific prompts and configuration details provided

🤔 Minor Improvements Needed

Front Matter

⚠️ Title capitalization: Should be "Appointment scheduling workflow" → "Appointment scheduling workflow" (only first word capitalized)

Writing Style

📝 Some passive voice instances:

• "The workflow uses visual nodes" → "Use visual nodes to create"
• "We will be creating" → "Create an appointment scheduling workflow"

Content Structure

💡 Overview could be more scannable:
The "What You'll Build" list is good, but consider adding a brief time estimate or difficulty level.

🎯 Prerequisites section:

• Add estimated setup time
• Consider mentioning technical skill level needed

Code Blocks

✨ Add more descriptive titles:

Could be:

🧩 Component Suggestions

💡 Consider adding callouts for important notes:

<Tip>
Remember to note the file IDs when uploading - you'll need them for the tools configuration.
</Tip>

🎯 Add a warning about testing:

<Warning>
Test each branch of your workflow thoroughly before going live to ensure all appointment scenarios work correctly.
</Warning>

📝 Specific Text Edits

Line 19: "We will be creating" → "You'll create"

Section 3, Step 1: The condition text could be clearer:
"Intent identified" → "Customer intent is determined"

Section 4: "Configure Inbound Settings" could use more context about why these settings matter.

🚀 Overall Assessment

This is a solid tutorial that follows most best practices! The structure is logical, the examples are concrete, and the use of MDX components enhances readability. The main areas for improvement are minor writing style tweaks and adding a few strategic callouts for important information.

Great work on creating a comprehensive workflow tutorial! 🎉

---

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

Documentation Review: Clinic Triage and Scheduling Workflow

Great work on this comprehensive medical workflow guide! 🎉 This is a well-structured and detailed implementation that covers all the essential aspects of a medical triage system. Here's my review:

✅ Strengths

🚀 Excellent Structure: The workflow progression from patient identification → triage assessment → routing is logical and follows real medical protocols.

✅ Proper Component Usage: Great use of <Steps> components instead of numbered lists throughout - this makes the instructions much more scannable.

🎯 Strong Safety Focus: The global emergency detection node and multiple routing options show excellent attention to patient safety.

💡 Realistic Scenarios: The integration examples with Epic, Cerner, and other real healthcare systems add practical value.

⚠️ Minor Issues to Address

📝 Title Capitalization: Your title "Clinic triage and scheduling workflow" should be "Clinic triage and scheduling workflow" (only first word capitalized).

🤔 Link Text: In the Prerequisites section, consider changing "A Vapi account" to use more descriptive text like "Create your Vapi account".

⚠️ Passive Voice: A few instances could be more active:

• "We will be creating" → "You'll create"
• "should be created" → "create these tools"

💡 Suggestions for Enhancement

✨ Add Code Block Titles: Your prompt examples would benefit from descriptive titles:

You are Nurse Kelly, a licensed medical assistant...

🧩 Consider Info Callout: The JSONPlaceholder explanation could use an <Info> callout instead of <Note> to better distinguish it as general information.

🎯 Emergency Detection Enhancement: Consider adding specific emergency keywords that trigger the global node:

chest pain, difficulty breathing, severe bleeding, unconscious, heart attack, stroke

🔥 Critical Medical Considerations

🚨 HIPAA Prominence: Consider moving the HIPAA warning closer to the top, as this is critical for medical implementations.

⚠️ Disclaimer Addition: Consider adding a medical disclaimer about the AI assistant not replacing professional medical judgment.

Overall Assessment

This is an excellent, production-ready workflow guide that demonstrates sophisticated understanding of both Vapi's capabilities and medical workflow requirements. The attention to safety protocols and real-world integration makes this particularly valuable. 🌟

Confidence Level: Very High - This guide effectively teaches users to build a comprehensive medical triage system while maintaining appropriate safety considerations.

---

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

Documentation Review for E-commerce Order Management Workflow

Overall Assessment ✅ 🎉

This is a comprehensive and well-structured documentation! The workflow example is practical and demonstrates real-world e-commerce customer service automation effectively. Great job on the detailed implementation guide!

Major Strengths 🚀

• Excellent structure: Clear progression from setup to implementation
• Practical examples: Real-world e-commerce scenarios that users can relate to
• Comprehensive coverage: Handles multiple customer service flows
• Good use of components: Proper , , and callouts throughout
• Real integration guidance: Includes actual API references for production use

Issues to Address

🚨 Critical: Numbered Lists Need Steps Component

Found several numbered lists that should use the <Steps> component:

Line 16-19 (What You'll Build section):

**What You'll Build:**
* Order tracking with real-time status updates
* Return processing with automated eligibility verification
* Customer tier routing (VIP, Premium, Standard)
* Global fraud detection and sentiment monitoring

Line 22-25 (Prerequisites section):

## Prerequisites

* A [Vapi account](https://dashboard.vapi.ai/).
* E-commerce platform or order management system.
* Shipping carrier integrations.

⚠️ These bullet points are fine as they're just lists, not sequential steps.

📝 Writing Style Improvements

Line 11: "Build an AI-powered e-commerce customer service workflow that handles..."
🎯 Consider shortening: "Build an AI customer service workflow that handles..."

Line 29: "We will be creating an order management workflow..."
📝 Use active voice: "Create an order management workflow..."

Line 85: "This example uses JSONPlaceholder, a free testing API..."
💡 Consider moving this important note higher or making it more prominent

🤔 Minor Content Suggestions

Global VIP Handler (Line 245):
The condition {{ customer_tier == "VIP" or total_orders > 50 or lifetime_value > 5000 }} uses template syntax that may not be clear to all readers.

💡 Consider adding a brief explanation of how these variables are populated from the customer lookup.

Tool Configuration (Lines 54-99):
The JSONPlaceholder URLs are used consistently, but it might be clearer to group all the "production replacement" notes together.

✨ Enhancement Opportunities

Line 380: The integration section is excellent!
💡 Consider adding a brief callout about API authentication and security best practices.

Missing Global Monitoring:
The overview mentions "global fraud detection and sentiment monitoring" but these aren't implemented in the workflow steps.
🎯 Either add these features or update the overview to match what's actually built.

Excellent Components Usage 🎉

• ✅ Perfect use of <Steps> throughout workflow building
• ✅ Great <Note> callouts for important information
• ✅ Excellent <Frame> usage for the final workflow image
• ✅ Good <video> integration for visual guidance

Final Recommendations

This documentation is very strong overall! The main improvements needed are:

1. 🎯 Convert bullet point lists to regular text where they're not sequential steps
2. 📝 Use more active voice in a few places
3. 💡 Consider adding the missing global monitoring features mentioned in overview
4. ✨ Group all "production integration" notes for better scannability

The content is comprehensive, practical, and well-organized. Users will find this very helpful for building their own e-commerce workflows! 🚀

---

📄 fern/workflows/overview.mdx

Looking at your workflows overview documentation, here's my review against the style guidelines:

✅ Things Done Well

🎉 Excellent structure - Clear progression from introduction to implementation details
🚀 Great use of Frames - All images are properly wrapped with descriptive alt text
✅ Consistent terminology - "Workflows" and node types used consistently throughout
🎯 Good MDX component usage - Proper use of <Frame> and <Warning> components
✅ Active voice - Most content uses active voice effectively
📝 Good link text - All links are descriptive (no "click here")

🔥 Major Issues to Fix

🚨 Title capitalization: Change "Workflows overview" to "Workflows Overview" - only first word should be capitalized unless it's a proper noun, but "Workflows" is the product name here

⚠️ Minor Issues & Improvements

📝 Section heading inconsistency:

• ## Workflow structure should be ## Workflow Structure (capitalize major words in headings)
• ## Node Types and Configuration - good
• ## Best practices should be ## Best Practices

🤔 Passive voice instances to convert:

• "It empowers developers" → "Workflows empowers developers"
• "Variables can be configured by:" → "Configure variables by:"
• "A node is connected to another node via an edge" → "Connect nodes using edges"

💡 Content suggestions:

• Consider adding a brief sentence about prerequisites or what users need before starting
• The "Common Use Patterns" section could benefit from brief examples for each pattern

✨ Great Opportunities

🎯 Consider adding a callout for the workflow structure section to emphasize the start node requirement:

<Note>
Every workflow must have exactly one start node that serves as the main entry point.
</Note>

🧩 The Best Practices section is well-organized with clear subsections - excellent structure!

🚀 Overall Assessment

This is a high-quality documentation page that follows most guidelines well. The content is comprehensive, well-structured, and provides clear value to users. The visual elements enhance understanding, and the progression from overview to implementation details is logical.

The main fixes needed are minor capitalization adjustments and converting a few passive voice instances. The content quality and organization are excellent! 🎉

---

📄 fern/docs.yml

Looking at your Fern documentation configuration file (docs.yml), this is actually a well-structured YAML configuration file rather than a traditional MDX documentation file. However, I can still provide valuable feedback based on documentation best practices! 🎯

✅ Things Done Well 🎉

Navigation Structure: Your information hierarchy is excellent - well-organized sections that logically flow from getting started to advanced topics.

Consistent Naming: Good use of descriptive page titles and consistent iconography throughout.

User Journey: The flow from "Get started" → "Assistant customization" → "Workflows" → "Best practices" follows a logical learning progression.

🤔 Areas for Improvement

Tab Organization: Consider if having 5 tabs (documentation, api-reference, sdks, changelog, mcp) might be overwhelming. Users often prefer 3-4 main sections.

Section Depth: Some sections are quite deep (4+ levels). For example:

Assistant customization → Tools → External tools → Google Calendar

Consider flattening some of these hierarchies for better scannability.

💡 Specific Suggestions

🎯 Title Consistency: Most titles follow good capitalization, but double-check these:

• "GoHighLevel" vs "Go High Level" (inconsistent in navigation)
• "JWT authentication" could be "JWT Authentication" for consistency

📝 Naming Improvements:

• "Transcribers (Text-to-speech)" should be "Transcribers (Speech-to-text)"
• Consider "LLM providers" instead of "Large language models" for brevity

🧩 Navigation Flow: Consider moving "Testing" closer to "Get started" since users often want to test early in their journey.

🚀 Overall Assessment

This is a comprehensive and well-organized documentation structure! The logical flow and clear categorization make it easy for users to find what they need. Just some minor tweaks to reduce cognitive load and ensure consistency would make it even better.

The redirect configuration is particularly thorough - great job maintaining backward compatibility! ✨

---

📄 fern/workflows/examples/lead-qualification.mdx

(no content)

---

📖 Style Guidelines | Thanks for contributing! 🙏✨

[github-actions]

🌿 Preview your docs: https://vapi-preview-4ee8c9f7-2d1b-463c-9c8f-63ee1efbea72.docs.buildwithfern.com