Why Open Source Software Should Invest in Evangelism

Open source shouldn’t be hard to get into

Introduction

We’ve all been told to get into open-source software development. It is heavily encouraged in the industry. We have events like Hacktoberfest which even give out prizes for contributing. We’ve been told it is very valued in the industry, looks good on your CV, provides valuable experience and makes you a better developer.

Even though all of those statements are true, open-source projects still lack contributors. Why is that?

The Problem — Case in Point

The reason why many developers find open-source hard to get into is simple — the resources explaining these complex systems are few and far between.

That’s right, there are not enough resources online that clearly explain what an open-source project does and more importantly — how it does it. I believe this lack of good quality resources negatively impacts the industry (I’ve already talked about how every software engineer should write articles).

The end result is that open-source projects are not as newbie-friendly as they could be. This, I imagine, significantly lowers the number of contributors that a project might get.

Even knowing what a project is about is insufficient. To meaningfully contribute to it you need to know it’s whole architecture. Such documentation for most projects either doesn’t exist or is hidden deep down in some wiki page with possibly outdated information.

The onboarding process for newcomers needs to be as smooth as possible. Remember, people are exploring a project in their own free time and therefore the inconvenience threshold required to move on is very low.

Examples

Note that this is not meant to poke holes at certain projects. Almost all open-source projects lack good software evangelism. These examples are here to simply prove a point, not to diminish the usefulness of any project. Even my very much beloved Apache Kafka struggles here.

Apache Camel

Its website gives a vague explanation with a lot of buzzwords. It itself has a section that says: “Too many buzzwords — what exactly is Camel? … There’s a great discussion about Camel at Stack Overflow.”

If a project’s own website points you to a Stack Overflow answer to describe what it does, you know that the documentation can be improved.

Envoy Proxy

The explanation for this project is buried in the documentation three clicks away (Docs -> Latest -> What is Envoy). I personally found that description unsatisfying.

Yet, there seems to exist a very clear video made by the creator of Envoy itself — here. This introductory video is seemingly nowhere to be found on the project’s website and instead had to be searched on YouTube.

I have to give props that the architecture overview and overall documentation though, they seem very exhaustive.

Fluentd

The diagrams on their website make it look like it is some sort of messaging system and it seems like I’m not the only one that confused it.

Apache Cassandra

While a database doesn’t need much explaining and Cassandra does have some information on its homepage, try opening up the documentation and taking a look at its architecture.

Cassandra’s architecture

How is a new contributor supposed to learn how this database functions and help develop it?

Apache Hadoop

The homepage does its job to list the components that make up Hadoop, but I cannot no single resources on there that shows how these components work together at all.

The list goes on…

Those were some examples I very quickly managed to scrape. I am sure that there are more extreme cases out there.

Harder Problem

Having an introductory piece is a low hanging fruit that every open-source project can make use of.

The harder problem to solve is having extensive documentation about the architecture and inner workings of a project. That is a whole other beast and requires a ton more work to do right.

I find that this is much more useful than a simple introductory piece as well. Introductions are more well-suited for users of the software — people who might be planning on integrating it with their own system. As a result, a lot more people are inclined and eligible to write introductory pieces since the users of a software are always more than the developers.

For a person to contribute, though, he needs to be familiar in how the project functions itself. This is where in-depth technical overviews come handy and most open-source projects lack that.You might say that it is all there in the code but I would argue that very few software engineers will willingly read through thousands of lines of code to understand how a project works from a high level. At least less so than those who would read a few thousand words in an article.

A Matter of Priorities

What I’m envisioning is a world where each open-source project gives top priority to their documentation and evangelism. An ideal state would be to have such extensive documentation such that a complete newbie could jump in, read a ton and be ready to contribute to a project. This new contributor would not need to ask any questions in the mailing-list, he would not have to read through a ton of verbose code and he would not have to extensively debug the system to gauge its behavior.

This theoretically shouldn’t be that hard to achieve — it can be just another step in the process. Example — before releasing a new version of the software, ensure there have been X pieces written on how the new features work, what they enable and how to set them up.

How open-source projects can achieve that is another question, but I for one would love to see Medium profiles from open-source projects 😉.

And don’t get me wrong — this is a hard problem to solve. I can see why the state of the industry is the way it is. All open-source projects are striving to make use of what little contributors they have to improve the software and release new features. Writing and editing technical articles does not directly improve the software. It indirectly helps it by attracting more contributors and easing the work done by newer, less-familiar people. And I find that is worth all the effort.

Thanks for taking the time to read through this article!

I sincerely hope this piece managed to convince you, or at least make you think, that open-source software would greatly benefit from more heavy software evangelism.

If, by any chance, you found this informative or thought it provided you with value, please make sure to give it as many claps you believe it deserves and consider sharing with a friend. I believe it is a worthy cause.

~Stanislav Kozlovski