Sunday night. It’s almost midnight. I have to wake up early tomorrow for school. But I’m working on a side project. I make a git commit and push it. And there’s the dreaded .DS_Store file in the change. This has happened dozens of time to me — committing unneeded files. I promised myself to make it the last time it happens.

Searching for a decent solution that works without any frills yields nothing. As a developer I say, “Well I can make a solution”. And so I did.

Hence

This post is a list of things I before, during and after making joe. In just a week of the “launch”, it got:

  • Over 500 stars on Github and became one of to top repositories

  • Over 1300 downloads on PyPI, unknown through Homebrew

  • Dozens and dozens of happy, more productive developers all over the world

You

There’s a general problem out there right now — everyone wants to make the next “trending repo”. While that in itself is not always an issue, people often miss the point of any creation — that is to solve a problem. And you know what’s the easiest problem to solve? It’s the one that you are experiencing. Here’s why:

  • You know exactly what the problem is. In my case, it was forgetting to make good .gitignore files and trying to find and download them just cumbersome.

  • You know what the pain feels like. In my case, the pain is having a bad code history out in the open or even in a private project.

  • You have an idea of what the solution is. In my case, it was making it easy to add a good .gitignore file without breaking a developer’s workflow (ie, through the command line).

Readme

The README is the first point of contact for potential users for your code. It’s one of the most important part of your project, often even more important than the code itself. Do not fuck it up.

I think the reason why joe became so popular is because of its README file. Here’s what you absolutely must have in the README file:

  • the title of the repo

  • a brief description of what the benefits of using your code are and

  • list some features.

Note the distinction between benefits and features — the former is a direct effect of using the software (eg. “makes you 10x more productive”) while the latter answers the question “how” (eg. “by learning your keystrokes”).

Then include detailed installation instructions followed by usage instructions. Make sure to dumb down both of these. Do not assume anything about your users other than the fact that they have no idea what you made and how it works. Include instructions for all platforms you support, any dependencies they might need (and how to get them) and alternative ways to get your software (more on this later).

Lastly, add instructions for potential contributors — how can other users contribute to this codebase? How can they modify the code, or where is the documentation for the code (more on this later) and so on.

Don’t leave out the README till the end, build it as you build the software. Always keep it updated and current.

Images

I used a mascot for my project. This was unique for me too and gave a personality to the tool.

Having a catchy image right on top of your README grabs the user’s attention and creates a sense of mystery and amusement. Most open source projects are thousands of lines of text which no one has the time to read. Include an image that gives your project a personality, and/or gives a demo of your project.

GIFs

GIFs are the foundation of modern web. I’m only partially kidding. I included a GIF of me using joe (made with LICEcap) and highlighting its core features. In my experience, having demo GIFs helps in reducing bounce rate on the repo, and increasing engagement with users. It’s true when they say “A GIF is worth a 1000 tutorials”.

Document

While joe didn’t need extensive documentation, there are always times when some projects need to be heavily documented. Use Github wiki or something similar for that. Make it dead easy for users to get help. Update the documentation as you build the software, and always keep it current.

You want to include everything from the README in the documentation too. Have a “Getting started” guide, and a detailed API reference. Include a section for potential contributors. Make it the hub for your project.

Distribute

So now you have a good solution for the problem. It would be naive to think that you are the only one with this problem. Package your code, and prepare for distribution.

Up until now, just like many other developers, I was guilty of not having great distribution channels. I just zipped my code, and expected users to figure things out. That is wrong.

Make it dead easy for anyone to install and use your software. This means:

  • Have explicit installation instructions for the platforms you support.

  • Have multiple distribution channels. In my case, I used Homebrew and Pypi. Mac users love Homebrew, and Linux users almost always have Pypi, or can build from source (instructions included).

  • Make it easier for others to contribute. I wrote a small script that made developing joe significantly easier for me and others.

Market

You know how they say “If you make it, they’ll come”? Whoever said this never knew what competition was.

If you make it, and market it, and then market it again, and then again, they might come.

It’s always a good idea to share with the world what you worked on. I use my Twitter network, Hacker News, Product Hunt and one or two relevant reddit’s subreddits for marketing. But that’s not it. Be active in those communities, and answer user questions and comments. Engage with people. Make them feel like they are heard and that their words matter.

Iterate

There is no such thing as perfect software. Shit can and will go wrong when you develop in public. You will get feedback and requests, do not ignore them. You will sometimes get questioned and criticized in a way you do not appreciate, but you will get used to ignoring all that.

In the case of joe, I made sure I was getting to all issues (or comments or pull requests) in a few hours, and resolving them. This builds trust with the users, and assures them that if they use my software and get stuck, help is there.

Take feedback seriously; it will only help you improve.

End

Open source is awesome, it’s super fun. But it takes time and effort and the right attitude. You have to be proactive, and willing to take action. You need to get out of your comfort zone, learn new things, apply new concepts. It can be unintuitive at times, but that’s the beauty of it.

The rewards are amazing, seeing people love what I made and talk about it, makes me extremely happy and proud.

If you are working on a cool and/or ridiculous side project, I’d love to know more about it. Hit me up on Twitter or via Email.

Thanks to Iheanyi Ekechukwu, Rohan Yelsangikar, Daniel Eckert and Sanny Lin for reading drafts of this.