If you want your OSS project to be successful…

Don’t take any of this too seriously because I wrote this really fast as I was procrastinating instead of working with some ugly legacy code today.

First off, I don’t know why the hell you’d pay attention to me because I’m only middling successful at OSS in terms of the effort I’ve put in over the years to whatever the benefits are. That being said, I do know quite a bit about what not to do, and that’s valuable.

First off, have the right idea and build something that solves some kind of common problem. It helps tremendously if you’re going into some kind of problem area without a lot of existing solutions. My aging StructureMap project was the very first production ready IoC tool for .Net. I seriously doubt it would have been terribly successful if it hadn’t been for that fact. Likewise, Marten has been successful because the idea of Postgresql as a Document Database just makes sense because of Postgresql’s unusually strong JSON support. I can say with some authority that the project concept was appealing because there were 3-4 other nascent OSS projects to do exactly what Marten became a couple years ago.

If you’re trying to go build a better mousetrap and walk into a problem domain with existing solutions, you just need to have some kind of compelling reason for folks to switch over to your tool. My example there would be Serilog. NLog or Log4Net are fine for what they are, but Serilog’s structured logging approach is different and provided some value beyond what the older logging alternatives did.

Try not to compete against some kind of tool from Microsoft itself. That’s just a losing proposition 95% of the time. And maybe realize upfront that the price of a significant success in .Net OSS means that Microsoft will eventually write their own version of whatever it is you’ve done.

Oh, and don’t do OSS at least in the .Net world if you’re trying to increase your professional visibility. I think it’s the other way around, you increase your visibility through talks, blog posts, and articles first. Then your OSS work will likely be more successful with more community visibility and credibility. Other folks might disagree with that, but that’s how I see it and what I’ve experienced myself both in good and bad ways.

If at all possible, dog-food your OSS project on a real work project. I can’t overstate how valuable that is to see how your tool really functions and to ensure it actually solves problems. The feedback cycle between finding a problem and getting it fixed is substantially faster when you’re dog-fooding your OSS project in a codebase where you have control versus getting GitHub issues from other people in code you’re not privy to. Moreover, it’s incredibly useful to see your colleagues using your OSS tool to find out how other folks reason about your tool’s API, try to apply it, and find out where you have usability issues. Lastly, you’re much more likely to have a good understanding of how to solve a technical problem that you actually have in your own projects.

All that being said about dog-fooding however, I’ve frequently used OSS work to teach myself new techniques, design ideas, and technologies.

Be as openly transparent about the project as you can early on and try to attract other contributors. Don’t go dark on a project or strive for perfection before releasing your project or starting to talk about it in public. I partially blame “going dark” prior to the v1.0 release for FubuMVC being such a colossal OSS failure for me. In 2011 I had a pretty packed room at CodeMash for a half day workshop on the very early FubuMVC, but I quit blogging or talking about it much for a couple years after that. When the FubuMVC team got a chance to do present again at CodeMash 2013 for the big v1.0 rollout, there were about a dozen people in the room and I was absolutely crushed.

Or just as valuable, try to get yourself some early adopters to get feedback and more ideas about the direction of the project. Not in terms of downloads and usage per se, but absolutely in terms of the technical achievement and community, Marten is by far and away the most successful OSS project I’ve had anything to do with over the years. A lot of this I would attribute to just having the right concept for a project, but much of that I believe is in how much effort I put into Marten very early on in publicizing it and blogging the project progress early. You know that saying that “with enough eyeballs, all bugs are shallow?” I have no idea if that’s actually true, but I can absolutely state that plenty of early user feedback and involvement has a magical ability to improve the usability of your OSS project.

Contributors come in all different types, and you want as many as you can attract. An eventual core team of contributors and project leaders is invaluable. Pull requests to implement functionality or fix bugs is certainly valuable. Someone who merely watches your project and occasionally points out usability problems or unclear documentation is absolutely helpful. People who take enough time to write useful GitHub issues contribute to projects getting better. Heck, folks who make itty bitty pull requests to improve the wording of the documentation help quite a bit, especially when there’s a bunch of those.

This deserves its own full fledged conversation, but make sure there’s enough README documentation and build automation to get new contributors up and running fast in the codebase. If you’re living in the .Net space, you make sure that folks can just open up Visual Studio.Net (or better IDE tools like JetBrains Rider;) and go. If there is any other kind of environment setup, get that scripted out where a simple “build” or “./build.sh” command of some sort or another build out whatever they need to run your code and especially the tests. Docker and docker-compose is turning out to be hugely helpful for this. This might force you to give up your favorite build automation tooling in favor of something mainstream (sorry Rake, I still love you). And don’t be like MS teams used to be and always use all kinds of weird Visual Studio.Net project extensions that aren’t on most folks’s box.

Documentation is unfortunately a big deal. It’s not just a matter of having documentation though, it’s also vital to make that documentation easy to edit and keep up to date because your project will change over time. Years ago I was frequently criticized online for StructureMap having essentially no documentation. As part of the huge (at the time) StructureMap 2.5 release I went and wrote up a ton of documentation with code samples in a big static HTML website. The 2.5 release had some annoying fluent interface APIs that nobody liked (including me), so I started introducing some streamlined API usage in 2.6 that still exists in the latest StructureMap (and Lamar) — which was great, except now the documentation was all out of date and people really laid into me online about that for years.

That horrendous experience with the StructureMap documentation led to me now having some personal rules for how I approach the technical documentation on ongoing OSS projects:

1. Make the project documentation website quick to re-publish because it’s going to change over time. Your best hope to keeping documentation up to date is to make it as painless as possible to update and publish documentation updates
2. Just give up and author your documentation in markdown one way or another because most developers at this point understand it
3. Embed code samples in the documentation in some sort of way where they can be kept up to date
4. As silly as it may sound, use some kind of “Edit me on GitHub” link in each page in your documentation website that let’s random people quickly whip up little pull requests to improve the documentation. You have no idea how helpful that’s been to me over the past 3-4 years.
5. Make it easy to update and preview the documentation website locally. That helps tremendously for other folks making little contributions.

There are other solutions for the living documentation idea, but all of the projects I’m involved with use the Storyteller “stdocs” tooling (which I of course wrote over years of dog-fooding:)) to manage “living documentation” websites.

Try to be responsive to user problems and questions. This is a “do as I say, not as I do” kind of thing because I can frequently be slow to acknowledge GitHub issues or questions at times. Just letting them know that “I saw this” can buy you some good will. Try to be cool in the face of folks being assholes to you online. Remember that interactions and folks generally come off worse online than they would in real life with body language cues, and also remember that you’re generally dealing with people when they’re already frustrated.

Assuming that your project is on GitHub, I highly recommend Gitter as a way to communicate with users. I find the two way communication a lot faster to help unwind user problems compared to working asynchronously in GitHub issues.