Migrating from Confluence to Understudy: A Step-by-Step Guide
Confluence has been the enterprise knowledge management default for years. It's powerful, deeply integrated with the Atlassian ecosystem, and incredibly flexible.
It's also, for many teams, slowly becoming a graveyard.
Not because Confluence is bad software — it's excellent at what it does. The problem is that most teams use about 15% of its capabilities while paying 100% of the complexity tax. Pages pile up. Nobody knows what's current. The search returns 47 results and none of them are what you need.
If you're reading this, you've probably already decided that something needs to change. Here's how to make the transition without losing what matters.
Before You Migrate: The Knowledge Audit
Don't try to move everything. That's the single biggest mistake teams make when leaving Confluence.
Start by categorizing your content:
Move immediately:
- Active project documentation
- Onboarding guides currently in use
- Process documentation that people reference weekly
- Decision records from the last 12 months
Move selectively:
- Meeting notes (only decisions, not transcripts)
- Technical specs (only for active systems)
- Team procedures that are still accurate
Leave behind:
- Pages last edited 18+ months ago with no views
- Duplicate or conflicting versions of the same doc
- Auto-generated content nobody reads
- Personal scratch spaces
Most teams find that 30-40% of their Confluence content is actively useful. The rest is digital clutter that migrating would just move from one system to another.
Step 1: Export Your Content
Confluence offers several export options:
Space export (recommended):
- Go to Space Settings → Content Tools → Export
- Choose HTML or XML export
- Select "Include attachments" if you need images and files
- Download the export file
Individual page export:
- For selective migration, export specific pages as Word or PDF
- Useful when you're only migrating certain spaces
API export (for large teams):
- Use the Confluence REST API for programmatic export
- Best for teams with 1,000+ pages
Save your exports somewhere accessible. You'll reference them during the transition.
Step 2: Restructure Before You Import
Confluence's structure (spaces → pages → child pages) doesn't always map cleanly to how people actually find information.
Before importing, ask your team:
- "When you need to find something, what do you search for?"
- "Which 10 pages do you visit most often?"
- "What information do you wish was easier to find?"
Use the answers to build your Understudy structure around how people think, not how Confluence organized it.
Common restructuring patterns:
- By team function instead of by project
- By workflow step instead of by document type
- By question ("How do I deploy?") instead of by answer ("Deployment Guide v3.2")
Step 3: Set Up Continuous Capture
Here's where the real shift happens. Confluence is a writing tool — someone has to sit down and create a page. Understudy is a capture tool — knowledge gets extracted from conversations, meetings, and everyday work.
Before migrating content, set up your capture workflows:
- Connect your communication tools (Slack, Notion)
- Configure automatic knowledge extraction
- Set up review workflows so captured knowledge gets validated
This way, new knowledge starts flowing into Understudy immediately, even before your old content is fully migrated.
Step 4: Migrate in Waves
Don't do a big-bang migration. Move content in waves:
Wave 1 (Week 1): Most-accessed content
- Top 20 pages by view count
- Current onboarding materials
- Active project docs
Wave 2 (Week 2-3): Team-critical content
- Process documentation
- Technical architecture docs
- Decision records
Wave 3 (Week 4+): Everything else worth keeping
- Historical project docs
- Reference materials
- Templates and standards
Between each wave, check in with your team:
- Can they find what they need?
- Is anything missing?
- Does the structure make sense?
Step 5: Run Both Systems in Parallel
Don't turn off Confluence on day one. Run both systems for 2-4 weeks.
During the parallel period:
- New content goes into Understudy only
- Old content is still accessible in Confluence (read-only)
- Set a clear sunset date and communicate it
This gives people time to adjust without the panic of losing access to familiar content.
Step 6: Sunset Confluence
Once your team is comfortable:
- Make Confluence read-only
- Keep it accessible for 90 days as an archive
- Export a final backup
- Cancel your Confluence subscription
What You Gain
The switch from Confluence to Understudy isn't just a tool change. It's a philosophy change:
- From writing to capturing — knowledge gets documented as a byproduct of work, not a separate task
- From organizing to finding — AI-powered search means structure matters less
- From maintaining to evolving — content stays fresh because it's continuously updated from real conversations
Teams that make this switch typically see:
- 60% reduction in time spent creating documentation
- 3x improvement in knowledge findability
- 40% faster onboarding for new hires
The Honest Trade-offs
Understudy isn't Confluence. Some things you'll miss:
- Deep Jira integration (Understudy integrates with Linear and Asana instead)
- Page-level permissions (Understudy uses team-level access)
- Confluence's macro ecosystem
Some things you won't miss:
- Page trees that go 7 levels deep
- "This page is out of date" warnings on every other doc
- Spending Friday afternoons updating documentation nobody asked for