Making better Github projects

I have been using Github a bit more lately, I have seen a lot of awesome GitHub projects and some not so great ones. This has helped me to get an idea of what is the difference between a good and great project. In this blog, I want to pass those insights on to you.

Readme

The number one issue I see with projects is the lack of a Readme. Readme is a good way to explain what your project does, it shows your ability to document things and to explain ideas succinctly. Furthermore, it would help people looking at your code to better understand your project. By skipping out on the readme you are tossing away a great tool in your toolbox.

Use your Readme as a method to explain what problem you are trying to solve, how to set up your project, explain the future of your project and so on. Make sure you do not have any glaring spelling errors in your Readme.

Demo

Have a live demo for your website or tool if it is hostable if not have a gif in your Readme. Someone viewing your project repo, wouldn't bother installing it in their own machines, unless you can demonstrate it is worthwhile of their time.

I have used Heroku to host some of my projects mainly because of the ease of pushing to production, I have also seen some netlify being used. Choose any of these platforms and host your project. Make sure your hosted website domain is clean and easily visible in your repo.

Repo

Pay attention to your Repo, having a.DS_Store in your repository will look very amateurish, this can be easily avoided by adding a .gitignore. Have a clear folder structure for your project, for example, have an src folder for your main code. You can look at other well established open-source projects for inspiration.

Something else good projects have in common is that they follow a commit philosophy, I have seen a lot of people make commits that wouldn’t make any sense if they were to look at it a few days later, don’t make this mistake, coding is a collaborative process, you are not writing the commit for yourself, you are writing it for your teammates, keep this in mind while you are writing commits. I try to follow the Angular commit style which is a very clean way to present your commits.

Another thing to do would be to add a license. A license in your repo increases the authenticity of your project and looks professional.

Profile

Ensure your profile has a professional username, this I learned the hard way because I thought it would be funny to have 420 in my profile name. There is no way that comes out looking good. Also in the domain of naming, make sure your project has an easily searchable name, as it would be otherwise very difficult for people to discover your project.

Blog

If you are working on concepts or ideas that do not have a lot of resources online, any information you have gathered, make sure you take notes and consolidate into a blog. This is a good way to give visibility to your projects and ideas and also in the process helps a lot of people.

I know the Internet is big on being modest and all forms of promotion are seen as bad but build useful things, people will appreciate it. At the end of the day number of stars and the number of forks count, it means you have made something meaningful, that has made an impact on the people around you. It is an extremely gratifying feeling that drives me a lot.

Hoping to write more of these based on your review.

TLDR;

1. Add a Readme.
2. Add a Demo.
3. Add .gitignore, follow commit philosophy.
4. Have a professional username.
5. Have a blog.

github