Going beyond documentation: Crafting VTEX’s award-winning Developer Portal

Thalita Uba
Thalita Uba December 21, 2023

Explore the behind-the-scenes story of our remarkable journey in creating the VTEX Developer Portal from scratch

Written by Júlia Rabello and Mariana Caetano and edited by Thalita Uba

The VTEX Developer Portal acts as a hub for frontend and backend developers, offering a comprehensive suite of resources for seamlessly integrating and building composable ecommerce solutions. Boasting an engaged community of over 25,000 monthly active developers spanning across 40 countries, the portal features a rich library of over 2,000 guides and an extensive 753-endpoint API reference, empowering developers with the tools necessary for innovation and efficiency in their projects.

The decision to create a documentation platform in-house was fueled by our identity as a technology company, with tech-savviness at our core. We recognized the need to streamline the management of this complex content. According to Bruno Amui, head of Documentation at VTEX,We believe good technical documentation should go beyond the basics. It’s not just about what’s efficient for us, but about embodying a profound respect for the developer community that surrounds us.” Building first-class experiences for ecommerce is challenging, and since VTEX is a composable and complete platform, many steps must be taken to make it happen.

VTEX Developer Portal

Embracing collaboration and feedback

Our commitment to corporate social responsibility led us to collaborate with VTEX Lab, a partnership program with Brazilian universities that are renowned for their technology programs. Design, Computer Science, and Computer Engineering university students play a pivotal role in projects such as the development of the VTEX Developer Portal, enabling both the developer community and budding professionals in universities, fostering a future generation of tech enthusiasts.

Throughout the development phase, we engaged in a comprehensive process of prototyping and interviewing users and partners, which provided critical insights that shaped the portal’s design and functionality. This user-centric approach ensured that the portal would genuinely meet the needs of the community it served.

The content migration was a meticulous process, as all technical writers in the team were focused on ensuring that the vast knowledge base seamlessly transitioned to the new portal. This process involved feedback loops with clients, categorization, and filtration of information. The invaluable input received from the developer community inspired several collaborative paths.

Our portal is fully open source, using docs as code techniques for managing and creating content collaboratively. Multiple feedback avenues, including suggesting edits through GitHub and user journey-based feedback forms, were integrated to capture diverse user perspectives. The portal fosters community engagement by enabling active participation from everyone to contribute to and improve documentation. Additionally, it showcases a “Contributors” section, recognizing and highlighting individuals pivotal in creating and improving the guide pages, thereby showcasing the community’s collaborative efforts with the company.

Building for the community

VTEX’s recent recognition as Best Interface Developer Portal at the DevPortal Awards is a testament to our commitment to providing an exceptional experience for developers worldwide. Celebrating our win is not just about recognition; it’s about acknowledging the challenges of maintaining a comprehensive documentation repository. We are proud to have developed a portal that not only meets but exceeds the expectations of the global developer community.

During the ceremony, the judges shared their thoughts about our Developer Portal:

“VTEX impressed us with their clean design. They packed in a lot of information without compromising whitespace. The site has many areas to explore but does not feel cramped or claustrophobic. They effectively use icons on the left overarching menu (Guides, API Reference, App Development…) to categorize site use cases. Search was a delight to use. This is especially important with so much information. VTEX delighted us with the human touch. We appreciated the names and profile pictures of the contributors to each page (via GitHub). The pencil icon on each page invites editors to contribute.”

Our journey reflects VTEX’s commitment to innovation, collaboration, and a user-centric approach. We look forward to continuing to support and empower developers worldwide through our composable and complete platform.