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.

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 lowering the barrier for anyone who wants to contribute, whether you're part of the team or from the community. Our documentation remains open source, the Write for the Community program is still going, and our contribution guidelines are public, detailed, and easy to follow.

To make reviews more actionable, we revamped our feedback system by embedding a feedback form directly on each documentation page. When someone submits feedback, a real-time notification is sent to our internal #documentation Slack channel. This means the technical writer responsible for this product is instantly informed and can quickly act on the suggestion, whether it's a fix, a clarification, or a request for new content.

Speaking of Slack, we still use a Slack bot to flag documentation that hasn’t been reviewed in over six months. Every Monday, a GitHub Actions workflow runs a script to scan all files for review dates. Any outdated files are collected, and the results are posted to a dedicated Slack channel via the Slack API so our technical writers can review the content to ensure everything is correct and up to date.

We also streamlined the contribution process for changelog entries by building an internal UI that anyone can use, without any experience with Git or GitHub. When someone submits a changelog entry through the interface, it automatically generates a pull request on GitHub, making it quick and easy for the documentation team to review it.

AI: From Hype to Help

Back in October, we integrated an external AI-powered chatbot into our documentation website. While it was a valuable experiment, we’ve since decommissioned it to make room for something better: our own custom AI chat interface built specifically for the Scaleway Docs.
This new interface helps users get answers directly from our documentation, offering real-time responses in the language of your choice, context-aware conversation history, Markdown support, user-friendly error messages, a reset option, and temporary session-based analytics.

While it’s built on the widely adopted OpenAI SDK, what truly makes it unique is its connection to our custom Scaleway Generative API endpoint. That’s where the intelligence happens, with vector search, RAG, and other enhancements powered by our internal infrastructure.

Behind the scenes, our engineers also developed a new docs-admin interface, giving the documentation team full control over the AI’s behavior. From editing the system prompt to managing responses, we can now iterate rapidly without redeploying or writing new code.

Final words: When Code Fails and People Leave, Docs Save

Our documentation is a key driver of discovery, adoption, and growth. It’s not just support material; it’s a core part of each product, and one of our strongest selling points. The docs are thriving, with exciting projects on the roadmap: a new use-case page to help users explore content in new ways, more automation tools like GitHub Actions, and, the cherry on top, a new Slack command for docs that I hope will rival even the beloved Giphy integration.

Plus, the developer portal is next up for an overhaul, promising even better experiences ahead. Keep an eye out!

Océane