Overview

We're excited to introduce our a new editing experience that brings powerful features including bi-directional Git syncing, MDX support, and a streamlined editing interface. This guide explains the migration process and what to expect based on your current setup.

Migration Eligibility

Your migration path depends on your current ReadMe configuration:

Waitlist Path

You'll see the waitlist option if you're currently using:

• Owlbot
• Manual Editor
• AWS Gateway Plugin

When you see the ReadMe Refactored banner (shown below), you can join the waitlist to be notified when migration becomes available for your project:

Direct Migration Path

If you're not using any of the features mentioned above, you may be eligible for immediate migration. You'll see an option to start the migration process directly.

Enterprise Customers

If you're an Enterprise customer, you'll see a message directing you to contact your Customer Success Manager to coordinate the migration.

Before You Migrate

Important considerations before clicking "Start Migration":

1. Non-Reversible Process: Once you migrate to the new editing experience, you cannot revert to the previous version.

2. Feature Compatibility: The new experience includes:

   • Direct editing in your docs
   • MDX support for enhanced interactivity
   • Bi-directional Git syncing
   • Improved search functionality

3. Data Preservation: All your existing documentation, including:

   • Guides
   • API References
   • Custom Pages
   • Recipes
   • Changelog entries
     will be preserved during migration.

Migration Process

For Waitlist Users

1. Click the "Learn more" button on the ReadMe Refactored banner
2. Review the new features and requirements
3. Click "Join waitlist" to register your interest
4. You'll receive an email notification when migration is available for your project

For Eligible Users

When you're eligible to migrate, you'll see a "ReadMe Refactored" banner in your dashboard with a "Start Migration" button. Here's what to expect:

1. Initial Migration Screen

   • You'll see the key features you'll get access to:
     • Bi-directional Git Syncing
     • 4 new components powered by MDX
     • Edit and view changes directly from your docs
   • Click Start Migration to begin.
   
   

2. During Migration

   • The process takes around 30 minutes
   • Your project dashboard will be temporarily disabled
   • Don't worry - your docs will remain live and accessible throughout the process
   • You'll see a progress indicator: "Migrating your docs to git..."
   • A launch video is available to watch while you wait
   

3. What's Being Upgraded

   • Your entire project is being migrated to a git-backed system
   • All existing content remains intact
   • Your documentation stays live during the entire process
   • You can contact [email protected] if you have any questions

4. Post-Migration Features
   After migration, you'll have access to:

   • Direct in-docs editing capabilities
   • New MDX components for creating beautiful docs faster
   • Bi-directional Git syncing options
   • No more switching between windows - edit right in your docs!

For Enterprise Users

🚧

Important Note for Enterprise Customers

The new ReadMe experience will be rolling out to Enterprise customers in early 2025. This includes features like bi-directional Git syncing, MDX components, and the new editing interface. For more details about the Enterprise rollout timeline or to discuss your specific migration needs, please contact your Customer Success Manager.

As an Enterprise customer, you'll see a special "ReadMe Refactored" banner in your dashboard with information specific to Enterprise migration. Here's what to expect:

1. Initial Notice

   • You'll see a notification that the new editing experience is slowly rolling out to Enterprise customers
   • The banner will highlight key Enterprise features:
     • Bi-directional Git syncing
     • MDX components
     • Direct in-docs editing
   • A Contact CSM button will be available

2. Next Steps

   • Click Contact CSM or reach out to your Customer Success Manager
   • Your CSM will:
     • Provide detailed information about Enterprise-specific features
     • Create a customized migration plan for your organization
     • Schedule a migration planning session
     • Coordinate the migration timing across your projects and groups
     • Ensure minimal disruption to your workflow

3. Enterprise-Specific Considerations

   • Group-level settings and permissions will be preserved
   • Staging environments will be migrated systematically
   • Branch management features will be enhanced
   • Audit logs will be maintained throughout the migration
   • Team collaboration features will be upgraded

4. Enterprise Features
   After migration, you'll have access to all standard features plus:

   • Advanced branch management
   • Enhanced team collaboration tools
   • Group-level controls
   • Comprehensive audit logging
   • Enterprise-grade security features

Post-Migration Steps

After migrating to the new experience:

1. Verify Content: Review all your documentation to ensure everything transferred correctly
2. Explore New Features: Familiarize yourself with:
   • The new editing interface
   • MDX capabilities
   • Git syncing options
3. Update Team Members: Inform your team about the new workflows
4. Review Permissions: Check and adjust user access levels if needed

Need Help?

If you encounter any issues during or after migration:

• Review our Migration FAQ
• Contact support through your dashboard
• Enterprise customers: Reach out to your CSM