How do make onboarding to BitFunnel easier?

I’ve been working on BitFunnel for roughly six months now. If I look at how I’ve used that time, my guess is that I’ve taken about a month of Mike’s time. If you look at the progress we’ve made, I think that’s a pretty good trade-off, but it doesn’t make for a scalable open source project.

It makes sense to invest a month of time in a full-time employee since they’re likely to be around for at least a year or two, and even in the case of an extraordinarily bad fit, they’ll probably stick around for long enough that you’ll get your time-investment back. But if it takes a month of your time to onboard a new open source contributor, that’s a losing proposition.

Mike and I often talk about his experience trying to help some MSR folks use BitFunnel as an example of the kind of thing we’d like to fix. We’ve made a lot of progress on that front; we now tend to write up tutorials of how to run the system as it exists when we make progress on adding functionality. Those documents are often a week or two behind the current code, but that’s not bad.

But if you look at the difficulty of not just running BitFunnel, but trying to actively contribute to it, that’s not so great. Things have improved a lot, but the onboarding process is still pretty rough. Mike has been pretty good about writing design notes for components but I haven’t been keeping up, and even if I was keeping up with Mike’s production of design notes, we might have eight of those documents insteasd of four, in a system where we have roughly 250 classes and are creating new classes all the time. That isn’t quite a fair comparison, because a design note can discuss multiple classes, but it gives you a rough idea of how much of the system doesn’t have design docs.

On my end, I can try to help by at least catching up to Mike’s production of design notes. I’ll also try to write a glossary, so that things that we haven’t deeply documented still have some explanation. I don’t think that’s enough, but I’m not sure what else to do.

We try to keep a list of issues tagged easy and we’ve gotten some pull requests as a result. That’s great, but there’s a huge gap between being able to fix easy issues and being able to make major contributions. We’d like to make it easier bridge the gap between fixing small issues and making large changes, but we’re not sure how to do that.

If you have any suggestions for how we can improve the situation for new contributors, please let us know.