AI-Powered Technical Documentation: How Scaleway uses Artificial Intelligence to transform user experience

AI in Technical Documentation

Chatbots are increasingly used across various sectors to facilitate user interaction and support. But despite their widespread use, many chatbots fail to meet user expectations due to their inability to provide specific and contextually appropriate answers. When it comes to solving technical issues, we want to turn to humans for help rather than robots. Robots too often respond to a question with a generic message that doesn't even address the issue in the first place.

However, it’s a common misconception that all chatbots are created equal.

What if we could build a chatbot that is smart enough to comprehend a complex knowledge base and consolidate different content into a single, personalized answer for the user? Well, this isn't just a hypothetical, it's a reality.

Meet Devana: Scaleway's AI-driven Documentation Chatbot

We are introducing Devana, our AI-powered solution integrated into our Documentation website. Unlike traditional chatbots that rely on scripted and limited response mechanisms, Devana uses Machine Learning and Retrieval-Augmented Generation (RAG) systems to understand and interpret user questions effectively. An example is detailed in the chatbot’s architecture section.

Thanks to RAG, Devana retrieves relevant data from the Documentation website and generates accurate and contextually rich responses.

While our Algolia-powered search engine already enhances your search experience, Devana takes it further. It goes beyond keyword dependency by understanding the context of your queries and delivering accurate, personalized responses in natural language.

Key Concepts to Understand Devana’s AI-Powered Documentation Platform

In the context of Devana's platform, understanding the following key terms is essential:

Agent: An agent refers to an AI-powered entity designed to perform specific tasks autonomously. These agents can process natural language queries, execute commands, interact with users, and potentially even engage in more complex decision-making processes based on their training.

Identity: Identity is generally tied to user accounts or profiles linked to specific agents. This identity system manages permissions, tracks interactions, and ensures that the AI agents can securely and accurately associate actions and data with the correct user. Therefore, for Scaleway, we had to build our own Identity.

Prompt: Refers to the initial input given to a language model to generate a response or perform a task. In Retrieval-Augmented Generation, a prompt typically includes the initial query or text and additional information retrieved from external sources (in our case, the Documentation website).

GenAI Model: A GenAI model on Devana refers to the generative AI models, such as those based on large language models (LLMs), used to power the agents. In this context, Devana is positioned as a company specializing in data preparation to create complex, high-dimensional vector systems.

Embeddings: Embeddings refer to numerical representations of words, phrases, or other types of data that capture their semantic meaning. AI models create these embeddings to map complex and unstructured data (like text) into a continuous vector space, where similar items are placed closer together. Words with similar meanings will have similar embeddings, allowing the agent to process and generate more relevant responses. Devana takes this a step further by incorporating an additional layer of technology that vectorizes metadata (title, description, paragraph, tags…, etc.) alongside the text. This approach preserves the structure of documents, including elements like headings and subheadings, ensuring the AI comprehends not only the content but also its organizational context.

💡If you’re not familiar with the term Vector Space, think of it like a map where each word in a language is represented by a point. This map is not a flat surface but a space with many dimensions (like a 3D space, but with many more directions). Each word is like a point on this map. If two words are similar in meaning (like "cat" and "dog"), their points are close to each other. If two words are very different (like "cat" and "table"), their points are far apart. Words are placed based on their meanings. Words with similar meanings are close together, which helps AI systems understand and work with language more effectively.

Devana's Unique Architecture

Devana uses Scaleway’s H100 PCIe GPU and L40S GPU Instances to run its applications. From Devana’s interface, admin users can efficiently configure GenAI models, integrate new files into the knowledge base, and seamlessly personalize the prompts. The GPU Instances provide the computational power needed for these tasks, ensuring a smooth and responsive user experience. The diagram below illustrates the major components and the flow of information through the system we put in place.

Here's how the process works:

• You submit a question to the chatbot from the Scaleway documentation website. For example, “Is Scaleway documentation open-source?”
• The chatbot forwards the question to the Retrieval Model. RAG swings into action! It scans your chosen data source for entries that match your question.
• With the most relevant information retrieved, RAG hands it over to the LLM, including your question and the appropriate details from the retrieved documents.
• The LLM uses the provided information to generate an accurate and helpful response telling you that Scaleway Documentation is open-source with a link to our GitHub repository. 🥰

How Scaleway’s Documentation Powers Devana’s AI-Driven Responses

Scaleway's technical documentation is the backbone of our chatbot's knowledge base. It's the primary resource the AI consults to provide accurate answers and explanations to user queries. Devana offers several identity modes for responding to users: Limited, Creative, and Unlimited.

For our purposes, we decided to go with the Limited identity to ensure that the AI draws content solely from the Documentation website. This ensures that the chatbot's responses are strictly aligned with the approved and accurate information, preventing it from introducing perspectives or ideas that might be incorrect or stray from Scaleway's vision. Devana's RAG control system also enables verification of a reply's relevance according to its knowledge database. Additionally, we have meticulously configured our agent's identity to align with our response expectations.

Our technical and UX writers continuously update the Documentation and Developers' websites, so we've implemented an automatic nightly synchronization to ensure that users always have access to the most up-to-date content.

Additionally, Devana allows us to manually add files or external sources to our agent, enabling us to refine and optimize the quality of responses bit by bit.

How the Chatbot's Identity is Configured for Scaleway's Needs

Internally, our documentation chatbot is called “Bobot”; our first step towards giving it a real identity. 😎

As mentioned earlier, we spent a great amount of time configuring the agent’s identity. A well-configured prompt ensures that the AI generates responses that are accurate and relevant to the user's query, pulling the correct information from the knowledge base.

Therefore, we built the agent with a comprehensive set of rules and guidelines, covering various aspects such as:

• Scope of expertise
• Tone of voice
• References to other cloud providers
• Handling of repeated questions
• Code generation

To maintain a sense of consistency and harmony, we also integrated Scaleway Documentation guidelines into the agent's training. Additionally, we gave it real-life examples and questions to ensure it fully grasped its role and could perform effectively.

Crafting a User-Centric Interface: Designing Devana’s Seamless Chatbot UI

We didn't want a chatbot that popped up at the bottom of a page like we see on so many websites. These lead customers to expect pre-constructed conversations with a bot that replies following a precise script. As a team, we wanted to put something more pleasing in place, so, we decided to go for a simple button next to the search bar. Elegant yet visible.

When clicked, a new page opens, delivering a smooth and responsive user experience. The user remains within the same interface. We kept the same look and feel to help minimize the disruption and enhance the overall usability.

On the front end, the page is built using Gatsby (soon NextJS 🤞), the same framework used for the Scaleway Documentation website. Gatsby allows for fast, static website generation, resulting in quick load times and a smooth browsing experience. The User Interface (UI) is developed with React. Communication between Scaleway UI and Devana is handled through a simple REST API.

The interface design uses Scaleway’s Ultraviolet Design System, ensuring true visual consistency across the website. This includes using specific colors, buttons, and fonts, all of which are part of the Ultraviolet system. As a result, the page maintains a cohesive look and feel, aligning with the overall Scaleway branding.

We integrated Devana into our applications using the open-source devana-react package. Along the project, we collaborated with Devana’s development team to address the limitations of certain non-customizable UI components, such as the language selector, the text input or the scroll functions. During the integration phase, we provided feedback on UI improvements, and the Devana team responded positively to enhance our branded integration. This collaboration has made our work more efficient, reducing the need for extensive custom overlays and allowing for a more seamless implementation.

Improving Scaleway's User Documentation with AI Insights

Thanks to our privileged relationship with Devana’s team, we were able to request custom data that was relevant to us in addition to the one offered by default. We are now monitoring:

• Token usage (input/output)
• Tokens by model type
• Number of users
• Number of conversations
• Average number of messages
• Rate of mistake
• Conversation history

Continuous Learning and Automated Updates

As of today, Devana has been launched in Beta to 20% of our users. Before rolling it out to our entire community, we want to take the time to gather valuable feedback and make any necessary enhancements to ensure the best possible experience. This phase includes rigorous testing to ensure that both the AI and the user interface function reliably in various scenarios, including responsiveness, user interactions, and error handling.

Our main goal is to create a better user experience, offer an improved search option, and optimize our documentation overall. With Devana, we want to make it easier for users to find the information they need quickly. The message history and statistics will also help us spot any gaps in our content, showing us what’s missing or could be improved. In addition, we are also able to provide answers in the language of the choice of the user which is a great advantage for our Documentation which is solely written in English. This ongoing effort will keep our documentation up-to-date, comprehensive, and user-friendly, making the platform more efficient and helpful for everyone.

AI’s Role in Shaping the Future of Cloud Documentation

Our journey wasn’t without its challenges, from choosing our AI provider to crafting the perfect prompt to designing an intuitive user interface to working as a team. Each small obstacle taught us something new, making the process as rewarding as it was challenging.

Today, Devana represents an easy entry point into AI-powered tools for our users. By engaging with an intelligent agent designed to enhance their experience, users can gradually become more comfortable with AI technologies, paving the way for broader integration into their workflows. And Scaleway can gradually leverage this experience to integrate AI into more of its products.

And while AI is at the heart of Devana, our documentation remains crafted by skilled hands. Benedikt, Luiza, Rowena, Néda, Samy, Justine, Jessica and Leanna to name a few. Their expertise ensures that the human touch is always present, guiding you every step of the way.

BONUS: Experience our chatbot in real life

To wrap up, feel free to watch this 2-minute video of our AI-powered Documentation Chatbot in action.

• New to Scaleway? Create an account now
• Want to visit the Documentation website? Check it out
• Want to learn more about the documentation website and the team? Read the associated content:
• Documentation at Scaleway
• The Hows and Whys of writing Technical Documentation
• Retrieval Augmented Generation: Buidling a RAG pipeline with Scaleway's Managed Inference