In the End, It’s the Documentation That Saves You

In the End, It’s the Documentation That Saves You Scale • Océane Franc • 11/08/25 • 10 min read

In the End, It’s the Documentation That Saves You!

In 2021, I wrote a blog post ( hello, younger version of me 👋) about the evolution of the Documentation Website at Scaleway. It was called " Further down the line, documentation will always matter. "

Since then, a lot has changed. I’ve gained a few wrinkles, but most importantly, we've launched a ton of new products, and our team has grown fast, which meant onboarding, training, and scaling knowledge like never before. Those challenges pushed us to rethink our entire documentation experience.

The result? A documentation platform that’s comprehensive, fast, and built to scale. It's structured for discoverability, optimized for clients, and rich with the context people need.

TL;DR: We built the kind of docs we always wished we had.

Scaleway Docs: Better Content & Better Structure

Over the past few years, Scaleway has pushed the limits of its cloud platform, launching more than 80 new products and features. From security best practices with IAM and Secret Manager, to cutting-edge AI tools like the Generative API and Managed Inference, the platform has expanded in every direction.

We’ve also strengthened our database offering with managed services for Redis, Serverless Databases, and MongoDB. On the networking side, we introduced VPCs, Public Gateways, and Edge Services, giving our users a complete, secure, and fully managed infrastructure. And while we’ve expanded our platform, we’ve stayed true to our roots with our bare metal servers, including Dedibox, Apple Silicon, and Elastic Metal.

More products inherently means more documentation, to give users the comprehensive, in-depth technical information they need for success.

So what changed in the docs?

A brand-new homepage , clean, visual, and user-friendly.

Dedicated product overview pages, like the IAM page , for clearer navigation and onboarding.

Interactive demos using Guideflow , step-by-step walkthroughs embedded right in the docs, helping users explore the console directly from the documentation website.

Fully automated product datasheet pipelines, no more manual copy-pasting from Excel and Confluence. We now generate product datasheets using a script tied to the Product Catalog API . This means your docs stay in sync with real-time updates.

A visual refresh using Ultraviolet components , bringing our components in line with Scaleway’s design system .

Revamped Changelog and FAQ pages, easier to read, easier to navigate.

A brand-new Troubleshooting hub , where every major product now has its dedicated troubleshooting page, making it easier to identify, resolve, and communicate common issues both for our support team and our customers.

Improved Search: Find What Matters, Fast

Our search engine is still powered by Algolia, and yes, the invoices are steep, but the improvement in user experience is worth it.

Last year, we rolled out a completely redesigned search experience on the documentation website. The new search bar now opens in a wide pop-up window, providing users with a clearer view of the results and content previews, making it easier to scan and select the right page. We've also added keyboard shortcut support to make navigation faster and more intuitive.

Most importantly, we've expanded our indexing. Previously, users could only search by title tag and sub-header. Now, the engine indexes the full content of each page, significantly improving the accuracy and relevance of results.

We’ve also been working with Algolia rules, which allow us to fine-tune search behavior based on user intent. With rules, we can boost or demote specific results, pin important content, or filter responses depending on the query. We use synonyms to support our bilingual audience, for example, linking “ moyen de paiement ” to “ carte bancaire ”. On top of which, we translate common French queries into English behind the scenes, ensuring relevant results even when users search in a language other than our docs.

Before the revamp, our No Search result rate peaked at 25.83% . After launching the new search experience, that number dropped to 19%. But the real game-changer came when we split the search index from the Scaleway console, giving the documentation its dedicated search repository. Since then, the No Search result rate has stabilized at an impressive 3% .

The Technical Stack Behind the Docs

I believe that documentation should be treated just like a product, with dedicated technical writers and engineers building and maintaining the platform it runs on. It’s not just about writing content; it’s about designing a system that scales, performs, and evolves alongside our infrastructure.

With that mindset, we completely rebuilt the documentation website from the ground up. The previous stack, based on an old version of Gatsby, had become difficult to maintain.

The website is still a static site built with React, and we still write our content in MDX. However, we’ve migrated from Gatsby to the latest version of Next.js, now using the App Router for a more modern and flexible architecture.

We also transitioned the entire codebase from JavaScript to 100% TypeScript, improving reliability and long-term maintainability. We've replaced the CSS-in-JS xstyled setup with CSS modules, making styling more maintainable, performant, and aligned with native CSS. As a result, the docs now share the same technology stack as scaleway.com, which makes maintenance and collaboration much easier for our engineering team. Read more about it on the dedicated Scaleway.com redesign blogpost .

Along with the technical stack overhaul, we’ve also aligned our UI components across the Scaleway Docs , Console , and Website , thanks to our design system Ultraviolet . Every UI component is now usable from the Storybook environment , allowing developers and contributors to preview and test components easily.

The result? Our build time dropped from over 30 minutes to just 7 for 1742 MDX files , integrated into our front-end monorepo, which also includes apps like scaleway.com or AI Pulse allowing for faster deployments. It’s a big win in terms of stability, maintainability, and speed, and a reflection of how seriously we take the docs platform as a product.

How We Handle Contributions and Feedback

At Scaleway, we’re committed to improving the content authoring experience and...