Why we use your open source project (or not)

While ‘shopping’ for some libraries, it struck me how many open source software projects are suffering from basic mistakes. Well, mistakes might sound too harsh. What I mean are those things you find on a project, which could be better. They are usually things not considered by the developer, as we (developers) were never told about them.

Doing 20+ years of open source development now, I can safely say I made many mistakes. Time to get them all fixed and document them, part of the open source community. I’m Michael Boelen , and you may know some of my work, like Rootkit Hunter (rkhunter) and Lynis. Here are some of the lessons I learned. You can use them next time when choosing a new open source project and make a better judgment call. If you are developer, then you can use these lessons to improve your own project.

Your website or project looks outdated

A first impression is everything, especially when it comes to new software. Your website looks outdated or has a copyright message on it of four years ago. It tells me the website is not maintained, so it makes me wonder if the software is any better.

Speaking about outdated software, this is a serious killer for getting new users on board. Even if you don’t do many updates, do release a small version now and then. This way we know the project is still alive.

Keep it up-to-date

When doing development on rkhunter, I had moments in which I did not have the time to work on the tool. And sometimes I simply had no energy to do so. The result was a tool that lacked updates, a lot of questions in my mailbox, and people asking for updates. To combat this, I handed over development to a group of people and retracted. That is an interesting subject in itself. But what the most important thing at the moment was for me is the continuous development of the project.

After I quit the rkhunter development, I started the security tool Lynis in 2007. For a long time, I could release versions. That is until my normal work got in the way. Long days of work and the development of Lynis came to a halt. With the lack of updates, people assumed the project was dead, which is also the rumor spread over several forums. The big lesson here is that people make assumptions, just by looking at a date. So one takeaway here is that it is better to release small and often, instead of releasing big updates.

First impression tips

Avoid old-looking websites like Sourceforge
Get up a simple website, that is quick and easy to read
Show me buttons with actions to take (like a download button)
Display the release date of versions
Set a three-month reminder to determine if a new version should be released

I simply don’t get it

You listed all the nice features your project has. What you forgot is to explain me why it matters and what problem you solve. And while we are it, I’m not even sure if I’m your target audience.

Adopted the power of story telling

Only a while ago I learned about the power of stories. Humans are programmed to tell stories, so we can relate it to our own experiences and share it with others. The Rootkit Hunter project never had a good story. The message was only about what it did. Things like the why and how were missing. That is something we fixed for Lynis obviously. While the perfect pitch always remains difficult, we have a better story now. And especially first time, we keep it simple in conversations. We compare Lynis with a health check at the doctor, or your the check your cars gets. Obviously then for Linux and specifically for security issues.

Tips for a better story

Explain who commonly uses it
Tell the benefits first, then list the features
Show technical requirements of the person needed to use the software
Ask your most active users to write a quick testimonial

Compile stuff

Please do not make me compile things. Yes, one day I have enough time to fully customize and make the perfect customized build, but not now. I still need to test your project and I want to do that quickly and see if we are a match.

Make it easy to use

Both projects are written in shell script. This helped a lot in getting it easily to work for others, as installation was not a requirement. It also avoids out-of-date software, as the latest version can easily be cloned from GitHub. Still, some of the users are not really familiar with permissions, and especially what the umask does. In Lynis a permission check is build in now, to ensure every new user is setting it up with the right ownership and permissions.

Simplicity tips

Provide a package or pre-compiled version
Have a page with installation tips, but keep it small and simple
Create a small movie

Can’t get it to work out of the box

So I installed your project and it refuses to work. It doesn’t start, or it doesn’t do what I expected it to do. Maybe it is my fault, maybe it is not. The error messages are vague and I have no idea what to do next. Well, I actually do: throw away the temporary directory I created. Don’t make me feel stupid and make sure that I have at least some results. Even if it is just a basic “Hello world” type of achievement.

Experience with users and skill levels

During the years I learned that there are two different types of users. Some do read the documentation first, then start using the software. Others take the reverse path and learn along the way. When you add skill level to these two options, things are more interesting. You will find that a lot of difficulties experienced by users never become visible to you as a developer.

With the rkhunter project, I learned that the audience was highly technical, directly from the start. Some of these early adopters even provided patches and feedback. But after a while that started to change. A more broad audience picked up on the tool. My mailbox filled up with questions like “How do I use this software?”.

Although there was a README available in the tarball of rkhunter, it was too technical and too long. Splitting up the documentation into different stages of usage would have been much better. We have taken this step with the Lynis project and the results are good. While it is hard to measure if every user can quickly finds what he or she needs, we know things have been improved. By splitting up the documentation we save people from searching around in the document. This is because they now directly get to the right document when using a search engine.

Tips for first use

Have a starter guide to help first-time users of the software
When I start the tool without any parameters, tell me what I can use
Have -h and --help as valid options and show me help instead of an error
Ask your users how they experienced the installation and first usage
Learn what documentation is visited often and keep improving it

Software was advertised incorrectly

Alright, I tried your software. Then I found out it was totally different than what I expected it to be. I removed it and most likely will never try it again.

Focus on your audience

No single tool can solve the problems for all of us. During the years of software development I learned that focus is important to achieve results, but also to attract the right type of users. Even in our business we use this principle by learning about our potential customers. If we believe someone is not a good fit, we will tell so and point them to another tool or even a competitor.

Tips for getting the right audience

Include screenshots
Show an instruction video to point out the main benefits
Have a clear description what the user can achieve with your project

Couldn’t find the license

Choosing the right software license is not easy. Especially if you just want to share the thing you created with the world and don’t care about how it is used. By making no clear choice, it is hard for others to use it.

Tips for selecting the right license

Pick the license that is close to your users (e.g. BSD for projects used on *BSD systems)
Consider what it means to you if others would earn money with your code

No mention of the author

You might have created a nice piece of software. What I still don’t know is who you are. You as the individual who created the software, or the team. You don’t have to put everything up. At least your name and why you created this software would make me feel much better. We might have a lot in common and I might even want to get in touch with you, liking sending a ’thanks’ message.

The power of open source

Many opportunities I had were due to my work on rkhunter. From getting a new job, a consultancy gig, and followers on Twitter and LinkedIn. I also received many books as a gift.

Tips for personal achievement

Linked your name to the project
Think about the possibilities open source contributions bring to your CV
Mention the project on your LinkedIn and other social media

Bonus step: promote your open source project

If you got all of these points covered, then it is time to take the next step. This can be achieved with the right way to promote your open source project and get more users. After all you wrote your code to help solving a problem, right? Make it count and get as much people to learn about the problem and solution. You may gain not only more users, but also contributors.

What mistakes did you make in your open source project? How did you solve it? Love to hear!