← Back to case study

Fixing Mintlify's Onboarding

A complete redesign of Mintlify's onboarding flow, breaking down the 10-step solution.

I recently came across a post from @Sammy_Digits that was a complaint about Mintlify's onboarding and decided to redesign it.

The Problem

Sam's issue: "After I signed up it made a git repo with no explanation and the only next step it suggested was to connect my domain, after that is done... what do I do?"

This is classic. No context, no guidance, no next steps.

The industry data shows what's at stake:

  • 77% of users abandon apps within 3 days (Source: Andrew Chen, a16z)
  • Top-quartile onboarding achieves 2.5x higher customer lifetime value (Source: McKinsey)
  • Getting users to their "aha moment" quickly is critical for retention

Mintlify had room for improvement in these areas.

Why It Matters

Bad onboarding = burned money.

You spend $500 to acquire Sam. He gets confused. He leaves. He never comes back. That $500? Gone.

Good onboarding might turn that $500 into years of revenue.

The Fix: 10 Steps

I redesigned the entire flow. Here's the breakdown:

1. Welcome + Timeline

"Beautiful docs in 5 minutes"

Sets clear expectations, reduces anxiety about time commitment. Users know exactly what they're getting into and how long it'll take. This prevents the "how much longer?" anxiety.

2. Ask Their Goal

Different users need different guidance. Someone migrating docs has different questions than someone starting fresh. By asking upfront, you can tailor the entire experience to their specific needs. Makes users feel understood from the start.

3. Show The Journey

Removes fear of the unknown. When users see it's just 3 steps, it feels manageable. Creates a mental roadmap so they're never wondering "how much more is there?"

Pro tip: Don't be scared of longer onboardings if you capture all info at once — better to let users enjoy the product freely afterward.

4 & 5. Foundation Before Code

Step 4: Account Setup — Get the basics out of the way: name, organization, optional password.

Step 5: Repository Connection — Show exactly what files you'll create BEFORE touching their repo.

This fixes Sam's main complaint!

Collecting account info first gets the "boring stuff" out of the way. Users can breeze through it knowing they're just setting up their profile.

Then when you get to repository connection — the scary part where you're modifying their code — they're mentally ready. And because you show exactly what will be created (mint.json, /docs folder, sample files) BEFORE creating it, you build massive trust.

Transparency before action = no surprises = happy developers.

6. Celebrate + Guide

"✓ Repo connected! Here's what we created. Next: Edit your first page"

Shows accomplishment (dopamine hit), explains what just happened, and provides clear next step. Users never feel lost because there's always an obvious action to take. The checklist format shows progress and creates momentum.

This fixes Sam's "what now?" moment.

7. Interactive Learning

Split screen: code on left, preview on right.

Learn by doing beats passive tutorials. Instant feedback builds confidence — users immediately see their changes come to life. This is especially powerful for developers who are used to this pattern from their IDEs.

8. Quick Wins

Customize logo and colors in real-time.

Tangible progress = satisfaction. Visual changes are immediately gratifying. Feels like you're building something, not just following instructions. When users see their branding appear, it becomes "theirs" psychologically.

9. Give Choice

Preview link, custom domain, or deploy later.

Respects user's timeline and comfort level. Some users want to test privately first. Others want to go live immediately. Forcing one path creates friction. The preview option solves Sam's problem — he could've had live docs in 30 seconds without domain setup.

10. Multiple Next Actions

"Your docs are live! You can: edit more, add domain, invite team, view analytics"

Prevents the dead end problem. Always show multiple paths forward so users can choose what matters to them. Some want to polish content, others want to invite teammates. No single "right" path means no wrong choices.

Principles That Work for Any Product

  1. Context Before Action — Explain what's about to happen and why
  2. Ask First, Guide Second — Understand user goals, personalize the journey
  3. Celebrate Progress — Every win deserves recognition
  4. No Dead Ends — Always show the next step
  5. Show Value Fast — "Aha moment" in minutes, not hours

Quick Wins You Can Do Today

Don't have time for a redesign? Start here:

  1. Add progress indicators — "Step 2 of 5" makes the unknown known. People complete when they see the finish line.

  2. Explain before big actions — "Here's what will happen when you click this"

  3. Fix dead ends — Every success screen needs 2-3 next actions

  4. Ask one goal question — "What brings you here?" = instant personalization

  5. Add "what's next" after signup — Prevents post-registration confusion

Each takes a day to build. Each addresses a real user pain point.

The Real Lesson

Sam didn't just complain — he gave free user research.

Most users just leave silently. When someone complains publicly, they actually wanted your product to work.

Treat complaints like gold.

And huge props to Mintlify's team for listening and responding. Most companies ignore feedback. They're doing it right.

Remember: It's not about adding more steps. It's about adding clarity at every step.

Context. Guidance. Progress. Choice. Next actions.

And here's the counterintuitive part: Long onboarding doesn't mean bad onboarding.