Hate to break it to you but the chances are that nobody cares about your software. I’m not trying to depress you. It sounds ruthless but most programmers are busy and don’t have time to read your open source project code to understand what it does, how to use it and what it’s meant for.
The majority of developers that stumble across your project are employed to build software for their companies. They do not wish to tear your project to pieces with harsh comments or announce to the world how bad it is. They’re merely people on a mission to get stuff done. Whether or not you agree with me, understanding their point of view can help you appreciate the people using your software and elevate your project to another level.
The Creator Mindset
As the creator, the more time you invest in your project, the harder it is to be objective about it. You grow fond of your project and believe that others should too. How you use variables, functions and modules creates envy among your peers. Your engineering skills are unparalleled in the company you work. Your code design achieves a perfect balance of beauty and speed.
So what?
Many software programmers tend to develop with a belief that their artisan software is self-evident to the programming masses. I myself was guilty of this once upon a time. Why bother with a documentation? Humph! Tutorials are for the uninitiated anyway. Anything that takes them away from writing the software is a waste of time. Heaven forbid, promoting their project is a sure sign of selling out to the Capitalist God.
It’s not a very productive attitude to embrace. Why leave all this work afloat in the vast ocean of open source software? If you wrote great software, and nobody uses it, was there any point in writing it in the first place?
The Fresh Perspective
The plight of most open source projects follows a pattern. A developer discovers a software project like a four leaf clover. They find it useful but not exactly matching their needs. So they decide to report an issue asking for the software to suck less and do things better. None of the appreciation and cult-like devotion that you originally expected materialises. Talk about a kick in the ego!
Over the years I learned that no matter how exciting your project may seem to you, all that most programmers care about is whether it solves their problem or not. They want to see an immediate benefit. That’s it. If your software almost fixes their problem then they may contribute an idea for improvement. If you’re very lucky, they may even find the time and contribute a patch. This realisation helped me change my attitude, moving from a solution-focused developer towards a more human-focused developer.
So what can you do to increase your odds and make people pay attention?
Explain and Connect
In your own head, the project you are pouring countless hours into all makes sense. But what about the others? If the project is to be useful to anybody else, taking the time to explain its utility in a Readme file seems like a good starting point. The leading question can be: Why would anyone care about this? Here you can explain the source of your idea. Has something frustrated you about the current state of the art? To me, frustration using other (often much more complex) solutions is the most potent reason to create a new project. Equally, some projects exist purely to satisfy my curiosity and are fun to develop. I wrote the lex utility in Ruby to learn how compiler lexing works. Whatever the reason, explain it.
What other stories could you tell? The tty-command Ruby project, for example, has a motivation section which tells a story of a startup founder that had to deal with hundreds of unruly and hard to manage Bash scripts and then rewrote them in Ruby, a more readable, elegant and fun language. A story is the quickest and the strongest communication link between your project and another developer. It differentiates your solution and demonstrates deliberate thought behind it.
Once you explain the background of your project, you can follow it up with a question: What is unique about my software that others should skip reading Hacker News? I often write down a list of features from the developer perspective and in their language, to help them understand the benefits. For example, if they are likely to be familiar with the active record pattern, I may use that as the analogy to explain the ease of using certain API calls.
Help Developers Solve their Problems
The very act of thinking about the answers to previous questions will put you in a new frame of mind and elevate your awareness about your project. The answers will potentially create a snowball effect and lead you further up the enlightenment tree. Once you explain why your project exists and how it differs from any other already present solution, it’s time to consider levels of engagement with the users of your software. Some good questions are:
- How does my project explain functionality to a first time user?
- How do I approach explaining things to programming beginners versus advanced developers?
- How do I help developers to be successful using my project?
- How do I demonstrate the perceived utility of my project?
- How can I motivate contribution and a higher level of involvement in the project?
- What is the vision? What will the project success look like once it is done?
These are example questions that helped and continue to provoke me to write documentation for many of my open source projects. For example, I like to add a content menu that makes it a breeze to find all available API calls. The tty-command project splits the menu between essential and advanced elements of the interface. A first time user can find what they need without feeling overwhelmed with all the features. Similarly, the advanced user can quickly learn about all the extra knobs they can regulate.
Irrespective of their experience level, tell developers how to install your project and show the simplest example of how to get started so that they can quickly bask in the glory of running code. Even better, record a demo. The tty-reader project displays animation of me line-editing text to demonstrate available capabilities. Therefore, the simpler your project is to setup and the more intuitive API that can be quickly understood, the better. I often create an examples folder of common use cases that quickly gives a taste of what the software can do. Of course, I would be lying if I said that I know how to answer these questions perfectly. The well of potential questions is deep and down to you to explore.
But there are questions that are not worth answering.
What Things to Leave out
Explaining why your software is much better by belittling other solutions is a loser’s game. You may protest. But wait - the other projects are so much worse. People surely should know. Not really, and here is why. Nobody seeks to build complex, buggy and unreliable software. A trail of design decisions that seemed great at the time ossifies the project. Against our best intentions, with time and many refactorings later, our software may change beyond recognition. Instead of looking and behaving like a majestic swan gliding on water, it acts more like a raccoon searching through the rubbish bin; it’s working but not very smoothly.
Whatever documentation you write, it’s important not to play hide and seek with people and bury key information under marketing slogans. Programmers are perceptive and you don’t want to discourage them prematurely. Spare them the trouble. Instead, consider giving impartial information backed by benchmarks and examples. Once a programmer satisfies their need, they may consider using your software for other things and let their fellow developers know about it. Word of mouth is a powerful and underrated channel in the programmer circles.
If you want your open source project to be recognised and valued, you will need to work hard at explaining its purpose. Don’t count on some famous developer to sprinkle some stardust and bless your project. It has to stand on its own merit. I wrote and released many Ruby packages. Only in recent times, I notice that people start paying attention and use my libraries in their code. Sadly, winning the adulation and the hearts of many programmers is often easier said than done. The truth is, even the best software doesn’t always attract the attention it deserves.
Stick with the Process
The good part of nobody knowing about your project is that it leaves you the liberty to do the right thing. So what could doing the right thing look like? You engage in refactoring your code with a long-term view. You fix all the broken windows. This may mean replacing awkward object inheritance with a chain of simple method calls. You spend time polishing existing features to handle corner cases or invalid inputs. You look at removing features that don’t match your goals or clash with the project vision. You improve your test coverage, ensuring tests are fast and comprehensive. Basically, you do all the stuff you should do to have a well-maintained project. The act of maintenance with time creates a good software project. This surprisingly may lead to people starting to care about your software.