When did you first reach for Twilio's documentation? When did you last?

Your experience with our docs likely tells a story, one that could range from seamless discovery, to occasional moments of foraging among many pages for clarity.

Let's go on a little journey through the history of Twilio's documentation. This epic unfolds as we detail the results of our massive migration effort, transforming more than 5,000 pages into a highly sophisticated platform, significantly boosting site performance, enhancing accessibility, and refreshing our user interface to provide a modern experience. By the end of this story, we hope you'll be as excited about our new beginning as we are.

Ask your developer

Twilio has always been a developer-focused company. Behind the "ASK YOUR DEVELOPER" billboard was a company by developers, for developers, building APIs. As any developer knows, documentation is critical when integrating an API. That's why Twilio invested in its documentation early, helping pioneer what are now best practices, such as automatically generating API reference pages from specifications, and providing tested code samples that developers can copy, paste, and run.

From conferences to forums to social media, we often heard how much developers appreciated our docs. But gradually, we noticed developers' enthusiasm and praise quieted, prompting us to rethink our approach and evolve our work.

Scale, technical debt, opportunity

While Twilio was enjoying its reputation for excellent technical documentation, it was also scaling rapidly. Today, our documentation houses more than 5,000 pages and nearly 20,000 code samples across nine coding languages.

What made the Twilio docs platform so inviting to build upon, left it burdened by both technical and content debt as projects and features were added but never fully removed.

What should have been relatively straightforward tasks, such as re-organizing pages to better guide customers or modifying the navigation, became difficult chores. As our product portfolio expanded, maintaining the documentation became increasingly complex, challenging our ability to swiftly respond to customer requests.

As with any tale of technical debt, the technology isn't the real story. Around us, the industry had moved beyond content management systems to statically generated sites served from the edge. The docs as code (DaC) movement had taken hold. There were truly better ways to build for our needs. We had an opportunity to take a massive leap into the present and build a foundation for the future.

A little over a year ago, we embarked on a mission to take that leap.

The principles for this change

We began our reconstruction project with several principles in mind:

• Significant user experience improvement: We recognized the need to address bugs, technical debt, and architectural decisions that affected our site's performance. We wanted not only to boost site performance and accessibility, but also to revitalize the look and feel.
• Streamlined collaboration: Twilio thrives on collective wisdom. We want our entire organization to contribute to the documentation effortlessly. Achieving this meant implementing a system that could seamlessly track changes and offer quick feedback loops.
• Enhanced flexibility for feature development: Innovation is at the heart of what we do. To stay ahead, we aimed to infuse our documentation system with the flexibility needed to develop and integrate new features. We knew that all of our changes wouldn't matter much if we didn't design a system that could continue to incorporate changes in the future.
• Zero downtime: An essential part of our mission was to ensure that these changes would not disrupt access to the documentation. Recognizing the critical nature of our documentation for customers, we committed to a seamless transition with no customer-facing downtime.

The approach

Twilio's Developer Education team (the guardians of the Docs platform and content), decided to embrace the Docs as Code philosophy. By treating documentation like code, this approach enables more consistency, reliability, and collaboration because documentation can be tested, modified at build time, and reviewed before release. It also unlocks the potential for greater innovation through modern development practices and tools.

We're excited to share more technical details from our engineers in upcoming posts where we'll dive deeper into how we implemented the decisions summarized below.

Significant user experience improvement

After a lot of consideration, we chose to build on Next.js for its flexibility and support. Next.js provides an incredible set of features and conventions on top of React, allowing us to statically generate pages while also remaining flexible enough to build some of the more complex things that make the Twilio documentation more dynamic than a typical content site.

Embracing Next.js also allowed us to easily integrate Twilio's Paste design system, further ensuring consistency in the customer experience and allowing us to move quickly.

We host the new platform with Vercel where we get amazing Next.js support and serve everything as fast as possible.

Streamlined collaboration

To support authors and create a more flexible body of content, we chose to build with MDX. MDX allows us to ship a familiar Markdown syntax to our authors while building custom functionality with JSX and custom directives.

As authors write, they push commits to GitHub and collaborate on Pull Requests. Vercel helps us here as well by providing Preview Deployments for each PR with commenting functionality.

Enhanced flexibility for feature development

As noted above, a big part of our decision when choosing Next.js was that it gave us the ability to build with a modern component architecture. Modifying Twilio's previous platform was challenging because one change inevitably rippled through the whole system with unintended consequences. Today, we are able to build and test components that are modular and robust.

Zero downtime

To manage the build and migration, we implemented a milestone approach, strategically rolling out sections of our documentation, starting with Twilio CLI, while concurrently building the necessary supporting infrastructure. This meant we could build what was needed as it was needed and receive feedback at each milestone.

We have actually been shipping the new platform to customers in sections for the last ten months. We began with the product documentation that required the fewest features and iterated from there, finally moving the last of Twilio and SendGrid's documentation in May of this year.

The results of this massive migration effort

This migration wasn't just about technological upgrades; it was a leap towards realizing a more interconnected and engaging documentation experience. Here’s what we have achieved so far:

• Outstanding site performance: Our docs are loading faster than ever before! Our Lighthouse performance score jumped from 59 to 100, and our accessibility score climbed from 76 to 94!
• New authoring and collaboration experience: Our team can now more seamlessly review changes to the documentation and partner with contributors across the organization, ensuring a more cohesive and unified experience for customers.
• Fresh look and feel: We have incorporated significant improvements to our user interface across the entire site, highlighted by a comprehensive overhaul of our homepage.
• Renewed code samples: As Twilio has moved to the OpenAPI specification, we have started developing a new code sample generation tool and, throughout this process, have conducted an extensive audit, retested, and modernized our existing code samples.
• New home for the SendGrid documentation: As part of the migration, we’ve moved the SendGrid docs to the twilio.com domain. This change gives our customers a seamless experience across products and helps us reduce overhead when creating, reviewing, publishing, and measuring content.

What the future holds

Looking forward, we’re dedicated to refining the authoring experience for those new to the Docs as Code approach, making it as seamless and intuitive to contribute as possible.

In the longer term, we are excited to innovate and build again! We envision new ways of interacting with the documentation, providing fresh interfaces and pathways into the docs, and partnering with other builders to better serve our customers from this new foundation.

Stay tuned as we continue to evolve and improve our platform. We'll share more details as we go, including a few posts for developers that provide insight into how we make and implement technical decisions. The future of our docs is bright, and we can’t wait to share more exciting developments with you!

Dalia Molina is a Docs Platform Senior Manager on the Developer Education team at Twilio. Once a web developer and educator, she now leads technical teams with dedication, empowering innovation and problem-solving through the use of technology and creativity.

Wade Christensen is working to bring the future of developer documentation to life as the Product Manager for Twilio's docs platform. He relies on his background in developer tools, education, and developer relations to understand Twilio's audience and deliver tools they'll love to use.