7 mistakes you're probably making

The most common mistakes open source projects make and how to avoid them.
607 readers like this.
red pen editing mistakes
Image by:

Opensource.com

It can be tough to start a new open source project. You have an awesome idea in your head, but it takes work to turn it into a productive, healthy, engaging community. Sadly (as seems to be the case in practically anything), the same mistakes are made over and over again by new projects.

Here are some of the most common mistakes open source projects make and my recommendations for avoiding them.

1. Chatting instead of shipping

Of the thousands of open source projects that kick off, too many get stuck at the outset because of a bunch of discussions on a Slack channel, mailing list, issue, or elsewhere. The discussions bounce around the house, and the scope often grows more and more lavish to incorporate the many, sundry ideas and considerations.

An early open source principle—"release early, release often"—serves us well. Instead of trying to solve all the challenges, write code, put it in a repo, and start accepting pull requests. Your project will evolve, adapt, and improve more quickly when focused on code.

2. Trying to ship a perfect first release

Reid Hoffman, founder of LinkedIn, once famously said, "If you are not embarrassed by the first version of your product, you've launched too late."

This is especially true in new open source projects. It can be tempting to try to make your first release, or even your 1.0, as perfect as possible. Here's the thing: Most people are not going to notice your first release, so it really doesn't need to be perfect.

People notice, consume, and participate in open source projects as they evolve. Start shipping, get feedback, make improvements, and ship those improvements. This is how you build growth.

3. Trying to build a perfect infrastructure

One common pattern I see in new open source projects is that they want to ensure the infrastructure—the website, collaboration platforms (e.g. GitHub/GitLab), continuous integration and continuous deployment (CI/CD), and everything else—is as perfect as possible. This can result in having a decent chunk of code ready to ship that the project founders are uneasy about releasing because they fear the other, less-up-to-par bits of infrastructure seem a little hokey.

A classic example is the website. Some projects will hold off shipping until a full-featured, well-designed website is in place. Don't do this.

Focus on putting enough infrastructure in place to be able to collaborate to build software. Ship your software, raise awareness—this will build growth in your community. As you build growth, you'll get more hands on deck to help perfect your infrastructure.

4. Not enforcing the code of conduct

In recent years, issues with diversity and inclusion have bubbled to the surface. Naturally, we want to ensure our communities are diverse and inclusive. Regardless of this being the right thing to do, diverse communities simply deliver better results.

Many communities kick off without considering what kind of conduct they want to see. For many, it's a given that the community should be happy, fun, engaging, and inclusive.

Some projects formalize this by putting a code of conduct in place and posting it on their website. This is not enough. The way you enforce good conduct is to ensure that the project's leaders live and breathe good conduct. Always nip incidents of negative conduct in the bud. Don't just try to ignore bad behavior, as it can fester. Likewise, don't humiliate people if they put in a wrong foot. Often a friendly, private few words asking people to be more respectful can resolve the problem.

5. Losing focus

I know, I know, now it is starting to sound like work, right? Seriously though, while one of the major pleasures of open source is the unlimited creative potential, many projects struggle or shut down because they spread themselves and their focus too thin.

Don't try to be all things to all people. As your project picks up steam, there are going to be a million requests from enthusiastic users. Stay focused on your goals, yet always encourage people to join the project and expand its focus and potential.

Importantly though, while "patches welcome!" is a common response to the wish list, don't just look for patches, look for maintainers. The last thing you want to do is maintain technical debt for other people's work.

6. Having too many discussions in too many places

We are surrounded by a multitude of communication platforms such as Slack, Mattermost, mailing lists, IRC, forums, issues, video conferencing, and more. It can be tempting to have a presence in all these places to ensure you get everyone involved. This is a mistake.

As I discussed in Much ado about communication, there are different types of communication channels, which I broadly break into structured and unstructured channels.

I recommend the following guidelines:

  • All bugs and technical discussions live in GitHub/GitLab issues
  • Have a general "community clubhouse" on a forum powered by Discourse
  • Have a real-time chat channel where people can have quick and informal discussions

Each channel serves a different purpose, and not all are essential. Issues are the most important, followed by the others.

Again, stay focused and keep discussions fairly central, and this will build momentum.

7. Taking yourself too seriously

Finally, this is all supposed to be fun. Too many projects take themselves a little too seriously. Always focus on having fun, building great relationships among community members, and making each other laugh.

The fabric of open source is built on engaged, innovative community members with a creative flair for putting new ideas into action. Always maintain this nimble and creative spirit. It will help your project thrive.

Good luck, and if you have other ideas and recommendations for mistakes new projects should avoid, please share them in the comments.

Tags
Community management
Six Degrees column
Jono Bacon
User profile image.
Jono Bacon is a leading community manager, speaker, author, and podcaster. He is the founder of Jono Bacon Consulting which provides community strategy/execution, developer workflow, and other services. He also previously served as director of community at GitHub, Canonical, XPRIZE, OpenAdvantage, and consulted and advised a range of organizations.
More about me

16 Comments

Avatar
Yigit Kocak | August 2, 2017
No readers like this yet.

I enjoyed reading your productivity tips.
Thank you for the tips.

Here are my 2 cents:

- Documenting tasks, milestones, achievements, feedback etc.
- Tracking time & resources spent on tasks

Avatar
Austin Delamar | August 2, 2017
No readers like this yet.

Add project Goals in the README too. Seems like bigger projects have predefined goals probably because some users pull requests go in a different direction than the maintainer wishes.

Avatar
Greg Pittman | August 2, 2017
No readers like this yet.

Good job.
Your first item on chatting can be approached in part by early on setting up some kind of repository of information about the ideas, plans, and scope of the project. As it evolves this will have to evolve too, but it can be helpful to rein in a project that has become too broad and insufficiently deep to be meaningful to users.
Furthermore, this repository can become the core for the first documentation that is begun so that as early as possible, you're able to explain what the project is about in a coherent way to both users and possible future contributors.

Avatar
Shane Curcuru | August 2, 2017
No readers like this yet.

Thought experiment for a follow-on article: for new projects, which documentation is more important to focus on first: roadmaps and "How this cool thing will fix your widgets!" usage docs, or technical documentation, clear build scripts, and things that will attract potential contributors?

I.e. how do you think about improving the user experience, vs. improving the developer experience, for new projects getting started?

Let me know if you write that article too - if not I'll need to ponder it!

Avatar
Greg Pittman | August 3, 2017
No readers like this yet.

I think that, as early as possible, support for and creation of documentation should become part of the DNA of a project. The earlier this starts, the better job you can do to prevent the documentation molehill turning into a mountain. There is also a feedback loop whereby creating the documentation may end up disclosing some operational non-sequiturs that need to be taken care of in the code in some way.

Avatar
Tarus Balog | August 2, 2017
No readers like this yet.

This is pretty timely. Just yesterday I sent a note to the OpenNMS team about consolidating some of our communications channels.

For code it works well: we manage our code on github and issues using Jira. For "real time" communications we used to use IRC but have moved on to a mattermost instance (chat.opennms.com) with an IRC gateway, so that's covered.

But we still have mailing lists and an online forum called Ask OpenNMS. The lists are hosted at Sourceforge and I've suggested that we move everything to the forum. You can configure the forum to e-mail you when things are added, yet I know there will be some resistance to dropping the mailing lists.

Avatar
Shane Curcuru | August 2, 2017
No readers like this yet.

Good point. Key question: what tasks do you see each communication channel being used for? And just as importantly: what kinds of people use each communication channel?

Apache projects default to mailing lists (from our history), which tends to work for developers actively working on the code. Some larger projects have forums - for end user questions, configuration, and how to use the product as a whole.

Understanding if different kinds of conversations are focused - or perhaps trying to move one set of conversations (likely the developer / code building talk) first might help.

Avatar
Matthew Wilcox | August 2, 2017
No readers like this yet.

An article I read recently pointed out that "Will it scale?" is an awful question that shouldn't be asked in the early days of a project. You should use the quickest-to-write stupid algorithms that will do for now. If your project is any good, there will be a 2.0 release where you can replace that linked list with a tree. Or shard your database. Whatever. But if you try to scale in twenty different directions before shipping 1.0, you won't ship.

Avatar
Squid | August 2, 2017
No readers like this yet.

#2 (Trying to ship a perfect first release) is what destroyed most of my projects :(

Avatar
Shane Curcuru | August 2, 2017
No readers like this yet.

#2 and #3 are both engineer's symptoms: it's not ready yet, I don't want to ship until it's perfect! If you want to grow an open source project, how, *specifically* do you define growth?

It's growth in contributors that you want to foster. Not code. So "ship early, ship often" is critical, because newcomers will often start with downloading a *release*, and then - if they're interested - start looking at the code.

Most people out there aren't interested in your code. They're interested in what problems it solves for them. Having releases - even incomplete - are how newcomers start seeing if your project is interesting (to them!) or not.

Also:

Mistake #0: Not having a LICENSE, preferably a well-known one (MIT, Apache, GPL).

Mistake #... well, there's no number for this, it's a name: not having a good README. One that actually tells people what your code does, how to use it, and how to contribute (or *obvious* pointers to each of those!).

Huh, yeah, great article Jono, but there are a lot more numbers to add to it!

Avatar
Lewis Cowles | August 4, 2017
No readers like this yet.

2 & 3 IDK...

I Understand why it's bad to be a perfectionist and I'm pretty far from one (constantly learning means you can't be because tomorrow you learn more that needs considering).

I Just feel like not having good-enough infrastructure or quality can be damaging. I think an additional thing that is quite bad though is OpenSource (or Closed Source) development with profit being the primary driver. I think that will kill most projects faster than high-standards.

Avatar
Marcus D. Hanwell | August 4, 2017
No readers like this yet.

Great article, and I think it succinctly expresses a number of common pitfalls. Releases are tough, you want to make good, stable releases with all the features, but they need to be regular, and whilst I agree if you aren't (at least a little) embarrassed by your first release it is tough balancing that with showing enough promise. I have learned to relax more over the years.

Infrastructure building has gotten worse in recent years as the expectations have risen. I think it is a great thing, but it has to be tempered with actually getting stuff out there, moving forward, and I would say also ensuring you aren't investing too many resources in infrastructure to the detriment of shipping new features.

Nice write up, thanks for putting this together!

Avatar
Juustosiili | August 8, 2017
No readers like this yet.

Actually "enforcing the code of conduct" is a mistake which leads us to ideological echo chambers where diversity of thought is suppressed. That's probably the biggest mistake you can make. Google is the latest example of this kind of behaviour and their business is suffering because of that. And it's not like we haven't had people such as Eric S. Raymond make warnings about this phenomena for years now.

Related Content

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.