Successfully working with open source software

At Novvum, a big part of our success has come from working with open source tools. This paradigm is a distinguishing characteristic of the software industry and it’s like nothing I’ve seen before. Everyone from hobbyists to massive enterprises contribute to open source for FREE and everyone benefits from it.

As a boutique software agency, we had very little capital to work with when my co-founder, Raj, and I first started.

Having access to high quality software built by experts was a game-changer for us.

When I first started using open source software, it was overwhelming and sometimes intimidating. It took a lot of time and effort to figure out how to effectively navigate and utilize this vast ecosystem.

Whether you are trying to build an application or play around with machine learning, you need to find the right tool. This process can be overwhelming due to the sheer number of choices out there. So, how do we filter out the noise and use the tools effectively? Here’s what worked well for me:

Find the tools that fit your needs

First, decide which programming language you feel comfortable working with. Some languages are better suited for certain types of projects than others, so it is a good idea to educate yourself on that.

Next, do a simple google search and compile a list of options that seem to do what you would like. There are also a number of repositories on GitHub which are named awesome-[topic] which can be found here. They provide a curated list of awesome frameworks, libraries and software around the topic.

There are also passive ways of coming across new tools from places like Twitter and google news. I’ve found a lot of success coming across new libraries this way and there are many other options. The advantage of using Twitter is that if you follow the right people, they will check the quality of the tool before they post about it which could save you a lot of time. We do not necessarily have to go out looking for libraries — we can setup channels to receive new information as well.

Vet your tools

One big lesson I’ve learned is that a tool’s description might make it seem like it would to do exactly what is needed, but after further exploration, it is not flexible enough. The way to move forward from there is either to request the author for the new functionality or look for a different tool. Although there is no silver bullet for solving these problems, we can mitigate them early on. Here are a few quick things we could look out for ahead of time:

• Popularity: There is probably a good reason why so many developers are using the tool. It is a good indicator that it is flexible enough to fit a lot of different use-cases and that the maintainers are responsive enough to support all of these users. It doesn’t mean that one tool which is more popular than another is always the better choice, but it is a good indicator. Different ecosystems have different ways of determining popularity. For instance, Node.js has NPM package downloads and Python has PyPI statistics. GitHub stars are also helpful, but it is not an accurate representation of how many people are using the tool.
• Documentation: Detailed documentation says a lot about the quality of the project. Just like for any tool, we need an instruction manual on how to use it. I will explain more about how to effectively utilize the documentation in the next section, but at this stage, make sure that the documentation seems detailed enough.
• Maintenance: Evaluating the quality of the tool by its maintenance is tricky because there is no single rule. Some projects are very actively maintained while others have not been updated in years (we can look at the frequency of commits to the codebase to find this out). Either case might be preferable depending on what the tool does. If the tool implements something fundamental, like algorithms, then chances are it doesn’t need many updates. If it is a framework, then we would probably want it to be updated constantly to fix bugs, improve performance, or add new features.
• Issues: The issues section on GitHub can give us a lot of insights on what type of problems the tool has and how responsive the maintainers are. They are a good indicator of how flexible the library is.

Read the docs

Once we have taken the basic first steps of vetting the tools and narrow our choices, it is a good idea to dig into the documentation. We don’t need to read the documentation cover-to-cover, but it helps to skim over the different features that the tool offers to verify that it fits our use case and that it is easy to use. The technique I use here is that I keep my project’s requirements in the back of my mind as I read through the documentation while imagining how I would implement the features for my project. The key thing to note here is that -

we are not trying to understand the entirety of the library, we just need it for our purpose.

This process might take a little while and probably not something that can be done in one sitting. There are a couple of different ways to effectively utilize the documentation .

1. One way is to go through a portion of the documentation, step away from it, and imagine which of your features you could implement with what you know so far.
2. Keep in mind what you need for your project and skim through the documentation to find how the tool might be used. This is something that can be done during a commute (if you are not driving), during a lunch break, or whenever there is some time to spare.

Going through this process will help find any blatant issues which might not work with the project and it might give you ideas on how to get started.

Test them out

Reading the documentation can be very helpful, and if the tool seems to fit what you need, you can dig a little deeper. You can try out the tools in your project to see how it actually works. Another option is to make a mini project to test out the tool if it is too time consuming to incorporate into your main project.

This step is a lot more involved than the others and you may run into a few roadblocks. For instance, the documentation may not give you a full idea of how to implement certain features, so you could always dig into the source code. Peeking under the cover had answered many questions I’d had and it is definitely not as difficult as I first thought.

The source code may be too complex at times and it is not a plausible solution for understanding how to use the tool. Which brings us to our next section.

Reach out

There are many times when I’ve run into roadblocks during my implementation where either the documentation was not very clear or I did not have enough of an understanding of the tool. In those cases, it is very helpful to reach out and ask for help. There are a few different options to explore:

• StackOverflow: A simple google search using the name of the library and the feature you are trying to implement will usually point to a StackOverflow post. It is the go-to place to get answers to issues you may be having. If you are not able to find the right answer, you can always ask a question yourself. Just make sure to be very detailed when asking a question.
• Github issues: If the feature just does not exist, a good option would be to look through the tool’s GitHub issues. Others might have the same issue. You could also post an issue here and you are more likely to get a timely response from the authors of the library than from StackOverflow.
• Slack channel: Some OpenSource tools will have a slack workspace for people to discuss issues or ask questions. This would be the best way to get a quick response and your best opportunity to directly ask the people who maintain the tool. It is also a great way to build a relationship with the community since you would be speaking with them directly.

Contribute

OpenSource software is what it is today because of the tremendous amount of involvement from the community. If you haven’t found a tool that fits exactly what you need, then it is a great opportunity to contribute. The contribution could be something as simple as posting a GitHub issue, or as involved as implementing the feature yourself. This step might feel intimidating at first, but if you’ve gone through all of the above steps to get here, then there is a very valid use-case and other people might also benefit from your work. Here is a detailed guide on contributing to open source.

Contributing to an OpenSource software and displaying your work for the whole world to see and scrutinized may be scary for some people. I was certainly one of them. Having contributed anyway, I can say that the people scrutinizing your code are very friendly more often than not and they are just trying to help keep the quality of the tools they are using up to the highest standards. The perspective to take here is that we are all helping each other out to build awesome stuff. So have fun with it!

If you guys enjoyed reading this article, but feel like you need more details, please post a comment below. I am considering making this into a series where I go into more detail on each of the steps.