ReadMes are Important!

This article is primarily written about the platform GitHub. If you are unfamiliar with this platform, it might contain terms that will just confuse you. I recommend reading THIS first.

One of the nicest things to experience as a developer is when the things you made actually get used by people. That they find it actually useful (and usable). Having them suggest features, find bugs but generally just getting feedback to see that the thing you yourself (or your team) developed by yourself. Let me tell you it’s great. To get people to use your software, I believe it needs to:

  1. Have a purpose.
  2. Be in a usable state.
  3. Get attention.

The first two points should be clear. A hello world program isn’t really useful at all, and some joke programs / repos might get some Stars on github, or make for a good laugh, but no one will really USE the software in a conventional sense. The second point is self explanatory as well. Try to avoid critical bugs and have at least an usable UX. (User Experience). Pretty UI is cool and all, but the flow of how someone interacts with your software is more important. I don’t really need all these rainbow splash screens in CLI scripts, or some starting animations in my generic C# tool. The KISS principle applies. The third one is what I actually wanna write about. Because it often gets ignored. This part can generally be split into two steps as well:

  1. Share
  2. Convince

There isn’t really a big secret to sharing your Software. If you have Twitter, Reddit and Friends in real life, share your program on, well… Twitter, Reddit and with your friends! However now for the last, maybe most important step: Convince them to actually use it. After someone clicked that link and sees your Software what exactly would convince them to the go ahead and download, install and using it? The presentation aka the file! The ReadMe should contain everything to present and explain your Software. Depending on the size of the Project you use the whole ReadMe as an documentation or if its to big at least link to it. The readme is the face of your repo (if you don’t have an dedicated Website for it that is. ) it is what in the end makes People decide. A good readme is something I come back to when I need help installing the Software, getting it running or Troubleshooting when there is an FAQ or similar. My most “popular” repo with 57 stars gets about 2-5 unique views per week from the discovery queue. It has gathered up more views than lines of code by now! So to just sum it up, a good ReadMe makes your GitHub repos get recognized. With the rather new discovery feature GitHub added your repo will now automatically shown to people. There is no context as to why you made this project o explanation or anything as you might add when posting the repo somewhere else. Thus having all that info in a ReadMe just makes it more accessible and more likely to wake some interest. If you only use GitHub as a backup tool and don’t care about people starring your repos, congratulations! I just wasted your time.