Tiago in Opensourceland.
This is the story of Tiago, a software developer who visited Berlin for the first time in his life while attending a conference on IT, and how a particular talk sparked a desire to truly open source his projects.
Successful open source projects are ones that provide great documentation, welcome contributions, and keep both the product and community alive. A talk by Jan König at Landing Festival made me realise there’s a lot that developers need to do if they want their open source projects to be successful. So, without further ado, here’s what I’ve learned from Jan’s experience.
Release your inner writer.
Developers have a love/hate relationship with documentation: the dislike of creating documentation is proportional only to the despair of not finding it in other projects. Writing documentation is often seen as a lesser task. One that’s beneath the intellect of a developer who’d rather use it on demanding and challenging problems.
Think of it like this: every developer is an artist who cares only about creating masterpieces — and writing documentation is the software equivalent of washing the brushes.
Yet, the first thing a developer does when thinking about using someone else’s code is to dig into the documentation. More often than not, if the documentation is insufficient, the developer will move on and find some other library to use.
Documentation is the face of any library. It’s the first impression people are going to get of what awaits them. If you want people to use your code, the single most important thing you can do is show what your software does, what features it has, and how they can use it. People will judge your code from the documentation, and well structured, clear and extensive documentation is a sign of healthy code and good software.
But beyond encouraging people to use your code, your documentation can also tell people how they can modify, extend, customise and improve your library. Telling developers how they can contribute to your project is critical to its growth. Not only will you have more people helping you develop your code, but you’ll be showing other developers that the project is alive and kicking, and updated regularly.
Welcome contributions.
The wonder of the open source world is that anyone can contribute to your project and help you build your product. Developers will gladly help you build your software as long as those improvements are also handy for them. Any open source project that is perceived as good and useful will attract a community of developers willing to strengthen it.
If all goes well, you’ll find yourself with a great library: one that’s well structured, well coded and has features that everyone wants to use. But how do you get there? You need to make the act of contributing easy and attractive, that’s how.
Here’s a list of some of the most important points you need to address if you want people to contribute to your library.
1. Guidelines.
Avoid wasted time on both your end (by having a pull request that doesn’t fit your project’s style) and the contributor’s end (by writing code that won’t be used), by setting clear guidelines that specify the way you expect contributions to be done.
Some of the important areas to cover are:
- the expected level of detail of the commits’ text,
- the description of the pull request,
- A mention of the issue the pull request addresses,
- the name of the branch it should be done on,
- the minimum code coverage for the tests,
- a link to the style guide.
2. Make the first time easy.
A good way to motivate developers is to have some quick-to-fix issues and label them accordingly. Developers who submit their first PR are more likely to do it again and gradually move on to more challenging problems.
Jan said that at some point they thought of deliberately adding some orthography errors to their page so anyone could find them and fix them! Use all the tools available to create engagement.
3. Thank people for their contributions.
Everyone likes to have their work recognised and developers are no exception! A simple mention to your contributor’s work on your site or project will make them feel that their job is appreciated and they’ll feel some ownership of it. Don’t overlook the power of kindness. Of course, if your budget allows you, you can always reward them with 90.000 euros.
Communicate.
Every developer has, at some point, found a library they loved, only to drop it after not being able to find proper support for it. A good README file and architecture description takes you a long way but it’s never enough once you get your hands dirty. There’s always some endpoint that returns results you don’t expect or understand, or some small bug that annoys you.
On those occasions, it’s important to have some way of contacting the support team, so questions and doubts can be answered as fast as possible. Jan’s team went through the same problem and their experience could be useful for all open source projects.
Talk to us.
Jan’s first approach was to create a Slack channel where users could ask questions directly to the maintainers. Despite being a time consuming solution, it was an effective one: people would get the answers they needed fast, and they could get on with developing their code free from trouble. This seemed like the perfect solution and they thought they had one less problem on their hands. But as time went by, they realised the same questions were being asked over and over and their users couldn’t find them in the thousands of lines of written text.
They needed a new approach.
Let’s make it permanent.
Jan’s team decided to make the answers from the Slack channel publicly available on the Internet. After a lot of thinking, they went old-school and settled on creating a forum where everything was tagged and easily searchable. The most popular questions even had their own blog posts. They thought people would quickly find solutions to their issues, leaving Jan’s team with more time to develop their software. Jan’s team thought there was no way this solution wouldn’t work.
Except no one seemed to access the blog and ask questions or answer questions. The forum was quieter than a sleeping mouse and they couldn’t understand why. It seemed like they threw a party but everyone else went to a bigger, more popular one. What was going on?
Join the party everyone is already at.
The reason no-one was coming to the forum is because people were using search engines to find solutions to their problems, and their forum wasn’t coming up as one of the first results. This meant most developers weren’t finding it, and those that did weren’t willing to sign up to another forum.
“If only there was a widely popular platform for developers to share knowledge and help each other, that would reward people who are willing to help others and that everyone was already registered in,” said Jan, while he checked an answer to his own problem on StackOverflow.
Wait a second!
Eureka!
“Why don’t we use the tools we already have available and that everyone uses for our own benefit?”
In that moment, Jan’s company, Jovo, made a commitment to use StackOverflow as their de facto source for answering questions and keeping them permanent. This had a surprisingly good and unexpected outcome: not only could developers find answers to their problems more quickly, the app grew in popularity as the number of threads about it in StackOverflow grew.
Keep your product alive.
The world is changing. A dozen years ago smartphones were in an embryonic state and only a few techies owned one. Nowadays, the majority of people in developed countries carry one with them all the time. Smartphone apps became part of the pop culture and integrated into people’s everyday life. That’s how much the world can change in just a few years.
Web development, in particular, is changing at an even faster pace. Today, the majority of webpages are now accessed through mobile browsers, when just 5 years ago this number was only 16%. Every developer should cringe when they think about using a library that hasn’t been updated in over a year. The technologies they’re built on have certainly evolved, and libraries should be updated to reflect that. An inactive project also implies that it’s hard to find support for it.
So: keep your product alive! Adapt it to current times, use the latest stable updates of libraries (this is particularly important when security flaws are discovered), improve your code, and add the most requested features. Treat it like a plant that needs constant caring, trimming and watering to flourish.
Love your community.
When people are kind enough to devote their time helping developing projects they love, show them your gratitude. Do this by documenting your software, welcoming contributions, and creating a sense of community. Publicly thank your contributors, each and every one of them.
When your community makes contributions, review their pull requests as soon as you can and incorporate new contributions systematically. If there are any issues that get flagged repeatedly, give them high priority on your backlog. The same goes for any requirements that are constantly asked for.
There are highly skilled people out there who are willing to help you develop your open source products. By following Jan’s advice, you can make the most out of the opportunity — just like I plan to.
Tiago is a full-stack engineer at Vizzuality. He’s currently focused on the backend, contributing to projects such as Resource Watch.
