Documentation That Drives OSS Adoption: Lessons From Bruno

I've been working with Bruno, an open source API client, for more than two years and have been closely involved in building and maintaining its documentation from the ground up. While documenting both small and large features, I learned a lot about what works, what doesn't, and how documentation can become a growth driver for an open source project.

In this talk, I'll share real examples, mistakes we made, approaches that failed, and lessons that helped us improve the overall documentation experience. I'll cover topics such as creating an effective starter guide for new users, using analytics not just to measure page views but to understand where users struggle, and using product mockups to explain complex workflows that are difficult to communicate through text alone.

I'll also talk about our experience evaluating documentation platforms such as Nextra, Docusaurus, and MkDocs, and the lessons we learned while improving discoverability, searchability, and documentation structure. 

As AI-powered search and agents become a growing source of traffic, documentation also needs to be structured in a way that is easier for machines to understand and retrieve.

Target Audience - This talk is intended for open source maintainers, technical writers, Developer Relations professionals, developer advocates, product engineers, and contributors who are responsible for creating or maintaining documentation for developer-focused products.

Conclusion - Attendees will learn a practical framework for designing documentation that improves onboarding, increases discoverability, reduces support overhead, and drives both open source community growth and product adoption.

My goal with this talk is to share lessons learned from documenting Bruno and discuss how those learnings can be adapted to other open source projects.

Key takeaways from this session will be:

1. Why Starter Guides Matters  - The starter guide is often the first interaction users have with your product. I'll explain how a well-designed onboarding flow can help users experience value quickly and improve adoption.

2. How to Use Product Mockups Effectively - People often understand visuals faster than written explanations. I'll discuss when mockups are more effective than text, how we use them in documentation, and the challenges of keeping them updated as the product evolves.

3. Improving Documentation Search Experience - What users search for is not always how documentation is organized. I'll share practical approaches to structuring titles, navigation, and content around user intent. For example, a user may search for "developer tools" while the documentation refers to the same concept as "debugging tools."

4. How to Make Documentation AI-Friendly - As more content is consumed through AI tools and agents, documentation needs to provide clear context and structure. I'll share practical techniques for making documentation easier to discover, understand, and retrieve through modern AI-powered experiences.

5. How Feedback Loop Work - Continuous feedback from different sources is essential for improving documentation. Whether it comes from GitHub issues, community discussions, support requests, or analytics, feedback helps you understand what users are struggling with and where documentation gaps exist.