Create projects on GitHub like a Pro!
Introduction
Everyone knows the importance of GitHub in a CS Undergrad’s life. On GitHub, students upload their projects, their code, etc. GitHub is also used by industries, to monitor and utilise their products and workflow. We can clearly say that most of the MNC’s use GitHub as their version control platform. But for students, it is so much more. Many of us use GitHub pages, to show our resume as a website. Most of us use GitHub as a place for collaboration with different people, and so on.
It’s often said that we should not judge a book by its cover. But is that true in this case? No, it isn’t. Without a proper project description and structure, our project is as good as a couple of different and un-organized files. When a recruiter catches a glimpse of your project repository, he/she should be able to make out what it is, before going diving into the code. For this purpose, there arises a need for a proper type of documentation format, so that recruiters know what they are looking at, and also for a layman to understand what our project is all about.
How to differentiate a documented project from an undocumented one?
An undocumented project will look something like this:
As you can see, there is no documentation for this project. All a person can see is a bunch of files. Recruiters cannot get the gist of your project by looking at this. They need some type of documentation, to know what they are looking at.
Let’s look at the same project now, but with documentation now:
As you can see, the documented version is much better than the former, as people can actually read and understand the motivation behind our project, the various technologies we are implementing, and much more.
Different Sections regarding Documentation
The number and types of sections will differ from person to person. In this article, I will share the sections which I use and will be beneficial for everyone. The documentation is done on the README.md file.
1. Project Title, and a short description of the project.
For kicking things off, we need to have a title to our project. A project without its title is like a book without its title. To follow that, a 2–3 lines description of our project. As an example, I’ll be showing my project, CROPify to give you a more clear understanding:
2. Motivation and purpose of the project.
The motivation of a project is paramount, as it lets the recruiter/people know your purpose for creating the said project. In this example, I have listed down why I created CROPify:
3. Tech Stack and Resources used.
“Tech Stack” basically means the different technologies you have used for making your project. In my case, I use technologies like Flask, Sklearn etc. You can just list them, or you could put their logos directly. This approach looks better in your documentation.
“Resources” here mean the files you have used for making your project. As for me, I was working on a Data-Science project. So I had to use a dataset for model creation. That is why I put the link from where I got my dataset:
4. Algorithms/ Concepts used:
The basis of every project is a concept/ algorithm. We have to let our viewers know what algorithms we are using for our project, for them to understand our project in a profound manner.
If you are using a lot of algorithms, you could show them in a bar chart, according to their accuracy, R2 score, etc. This will help the viewers to understand the reason why you went with a specific algorithm.
5. Features Used:
Features are basically the parameters that go in your project, which give them functionality. For example in CROPify, I have created a web application, that would take different parameters like Nitrogen level, Phosphorus level, temperature etc, and the application would be able to predict what crop to grow in the respective field.
In this scenario, nitrogen level, phosphorus level act as different inputs to my application. This might be different for other projects, so you need to put the features that you think are important.
6. Functionality of the Project:
As the name suggests, in this section, you need to show/tell the basic functionality for your project. In CROPify, the functionality was that farmers would find out which crop they can cultivate, with added benefits like knowing the sowing and harvesting dates etc.
If a person wants to download and run your project locally, he needs to be able to do that. For this reason, I put a few steps, so that anyone could start working/using the project ASAP.
7. Screenshots/ Demo Video:
In this section, you need to put some screenshots of the project. This is done for people to take a look at the application without opening it.
The demo video must be in .gif format, as it takes less space and is faster than a normal video.
8. Issues and Future Improvements:
Issues are the problems that you are currently facing in the project, and future improvements are the improvements that you wish to add the future to your project.
These are very important, as it opens a potential way for people to contribute.
Few Additional Things To Add:
If you are planning to host your application, make sure to put the link in your documentation. This is because people always prefer a project that has been hosted over a local one.
If you participate in a Hackathon, you will be asked to submit a presentation or a Doc file for your project. Make sure to add those.
Conclusion:
If you follow this article, I’m pretty sure that your project will stand apart from others. I spent a lot of hours on GitHub, searching for projects with proper documentation. I couldn’t find many projects. Likewise, I hope this article will help you in your projects and hackathon submissions!
Things to Add:
The original link to the example I’ve used(CROPify): here
Connect with me here:
Linkedin: https://www.linkedin.com/in/jackson-sondi-0100/
Github: github.com/Jackson-hub
Instagram: https://www.instagram.com/j_24_07/
Stay in loop with the club:
Club Website : https://aiclubvitbhopal.github.io/
LinkedIn : https://www.linkedin.com/company/aiclub-vitb
Instagram: https://www.instagram.com/aiclub.vitb/?hl=en