Building documentation that converts users to contributors: A conversation with Bekah Hawrot Weigel
Bekah Hawrot Weigel shares how OpenSauced uses documentation to build contributor funnels, track success, and turn engaged users into long-term contributors.
Bekah Hawrot Weigel, currently at the Linux Foundation, brings a unique perspective to documentation — transitioning from teaching college English to technical writing, community building, and open source documentation leadership. Previously leading docs at OpenSauced before its acquisition, she’s passionate about documentation as a pathway for contribution and community growth.
We sat down to discuss how documentation serves as an onboarding tool, the challenges of maintaining docs in fast-moving open source projects, and the role of AI in creating personalized learning journeys.
It’s great to talk to you! First off, can you tell me about your background and how you came to work with documentation?
I’m based in Ohio and currently working at the Linux Foundation. My company got acquired by them, which kind of moved me over. It’s been an interesting transition — I moved because I was leading our docs at OpenSauced. It was a small team, like seven or eight people, but I was doing docs, education, and all the content. Now I’m not doing any of that stuff, so I’m trying to find my way back there, hopefully sooner rather than later.
My background is in teaching — I taught college English for ten years before moving into tech. Then I did some front-end work, and I started a community called Virtual Coffee that I’ve been running for the last five years. I’ve held so many different roles. Unfortunately, I came into tech and eight months later, COVID hit, so it’s been a really weird roller coaster. But content is near and dear to my heart. Documentation taps into the things that I’ve always loved doing.
And what were the metrics you tracked when you were leading documentation?
That’s a good question. Being a small team, there wasn’t a ton of focus on metrics, but there were a couple of things we wanted to see. Where are people turning to in the docs? Our guides got a lot of view time — people were interested in learning more about how this can help them in their particular use case.
The second part, because we were an open source project, was how many people are contributing and how many people continue to contribute to the docs. We were looking at that pathway — docs were kind of the entry point.
We had an education path too, which we ran alongisde our docs through Docusaurus. Education was step one — if you wanted to do something, we walked you through getting your first PR. The documentation site was kind of step two — you can be independent, you can contribute. And then our app, OpenSauced, if you made it there, you’ve gone through that full progression. We were looking for that as well.
We also looked at issues. How many people are creating issues? When people create issues it means they’re using the product. For us, that’s the ultimate goal. It was like, “Oh hey, this thing didn’t look right” or “this is not explained.” We moved very quickly, so things didn’t always get covered. It was nice knowing that people noticed.
So the documentation served as a funnel for open source contributors?
Yeah, exactly. All of our contributors were users as well — they were just invested. It was important to think about docs in terms of not just how can this serve a user, but how can this help onboard people to contributing? Because a lot of people came in with very, very little technical knowledge. They were trying to figure it out.
We wanted to give them something that had a low barrier to entry. It was really nice when we were able to do that successfully, when we provided them the foundation where they could take the next step and didn't feel like they were just so far beyond their capabilities.
And what do you think are the major challenges of maintaining docs, especially with community contributions?
I think one of the biggest challenges is matching contributors with the right level of complexity. It’s a learning process for maintainers — figuring out how to guide people toward issues that match their current skill level while still challenging them to grow. Sometimes someone would be really excited about an issue, but as a maintainer I’d realize the scope was larger than anticipated. That’s when I learned the importance of having honest conversations early about whether an issue is the right fit.
It’s tricky because you want to encourage contribution, but you also need to be realistic about the time investment for both the contributor and the review process. Finding that balance between supporting growth and maintaining project velocity is an ongoing challenge.
We also had situations where contributors would propose features that were genuinely valuable, but didn’t align with the project’s direction. Learning to say no constructively, even when the contribution represents real effort and enthusiasm, is a hard but necessary skill for maintainers.
The other challenge is consistency. At Virtual Coffee, we realize we’ve written things so many different ways. That’s the beautiful chaos of community documentation — you start with enthusiasm and openness, and then you look back and realize you need more structure. It’s amazing to get all the contributions, but then you need to figure out how to create coherence. That’s what we’re working on now — creating a style guide to help future contributors while honoring all the work that came before.
I also want to ask you about writing documentation for users with different levels of experience. How do you approach that?
I think it’s really important to meet users where they are. I’ve always loved that about documentation — you can provide different entry points. Some people need step-by-step guides. Some people just need API references. Some people want conceptual overviews first.
When you’re thinking about open source especially, you have this really wide range of technical abilities. The person who’s been coding for twenty years has very different needs than someone who’s trying to make their first contribution. Being able to segment that out and provide clear pathways for different skill levels is really important.
“I think AI can give you an individual journey. Even saying ‘hey, I know the basic implementation of this, I’m looking to go to the next step — can you help me find in the docs where I can get to the next step?’ Or ‘can you create a path for me?’ You kind of have that personalized journey that you can’t get otherwise.”
And did you structure the documentation in specific ways to support those different pathways?
We tried to have very clear categories. We had getting started guides that were very hand-holdy. Then we had our main documentation that assumed a bit more knowledge. And then we had more technical, in-depth pieces for people who really wanted to understand the architecture.
But honestly, one of the challenges was making sure people could find the right level for them. Navigation is hard. People don’t always know what they need until they start reading it, and then they realize “this is too basic” or “this is too advanced.”
Absolutely. To finish, we’d love to know what you see as the future of documentation, particularly with AI?
I think AI can give you an individual journey. Even saying, “hey, I know the basic implementation of this, I’m looking to go to the next step — can you help me find in the docs where I can get to the next step?” or, “can you create a path for me?”. You kind of have that personalized journey that you can’t get otherwise.
That’s really powerful, especially for people who are trying to navigate large documentation sites or understand where they fit in the learning curve. An LLM could help navigate there, even if it’s not about generating or consuming the content directly, but just helping you navigate the content.
Any final thoughts on what makes documentation successful?
What makes docs good is when people use them and they can help them succeed. That’s really what it comes down to. Whether it’s helping someone understand a feature, onboard a new contributor, or solve a problem — if the documentation enables that success, then it’s doing its job.
And I think being able to measure that success, whether through contribution rates, issue reports, or just usage patterns, helps you understand where you need to improve and where you’re doing well.
This interview was published on 15 October 2025, and conducted as part of research for the 2025 State of Docs report.