Why we use your open source project (or not)
Why we use your open source project (or not)
Your website or project looks outdatedKeep it up-to-dateFirst impression tipsI simply don’t get itAdopted the power of story tellingTips for a better storyCompile stuffMake it easy to useSimplicity tipsCan’t get it to work out of the boxExperience with users and skill levelsTips for first useSoftware was advertised incorrectlyFocus on your audienceTips for getting the right audienceCouldn’t find the licenseTips for selecting the right licenseNo mention of the authorThe power of open sourceTips for personal achievementBonus step: promote your open source projectWhile ‘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 outdatedA 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-dateWhen 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 tipsAvoid old-looking websites like SourceforgeGet up a simple website, that is quick and easy to readShow me buttons with actions to take (like a download button)Display the release date of versionsSet a three-month reminder to determine if a new version should be releasedI simply don’t get itYou 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 tellingOnly 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 storyExplain who commonly uses itTell the benefits first, then list the featuresShow technical requirements of the person needed to use the softwareAsk your most active users to write a quick testimonialCompile stuffPlease 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 useBoth 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 tipsProvide a package or pre-compiled versionHave a page with installation tips, but keep it small and simpleCreate a small movieCan’t get it to work out of the boxSo 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 levelsDuring 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 useHave a starter guide to help first-time users of the softwareWhen I start the tool without any parameters, tell me what I can useHave -h and --help as valid options and show me help instead of an errorAsk your users how they experienced the installation and first usageLearn what documentation is visited often and keep improving itSoftware was advertised incorrectlyAlright, 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 audienceNo 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 audienceInclude screenshotsShow an instruction video to point out the main benefitsHave a clear description what the user can achieve with your projectCouldn’t find the licenseChoosing 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 licensePick 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 codeYou 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 sourceMany 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 achievementLinked your name to the projectThink about the possibilities open source contributions bring to your CVMention the project on your LinkedIn and other social mediaIf 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](/how-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!