Photo of a brand new car without a plate number.
After reading this article you will see the reason why your project is not recognized or noticed by visitors on the platforms.
Imagine having a brand new car without a plate/registration number! What do you think will happen to the car? If the car is involved in negative situations for examples;
- If the car is stolen by hoodlums.
- If the car has an accident.
Let us judge the two scenarios; in the first case, would the car be recovered from the hoodlums by security operatives? The answer is NO! In the second case, would it be easy to get the identity of the car owner for any form of support? The answer is still NO! This is because the car is not registered with the government so the details of the car and the owner are unknown. As you can see not having a registration plate number on a car is very disastrous the disadvantages outweighed the advantages. The bottom line in both cases is the lack of recognition, no security agent would be able to identify the car and the owner's details.
The above-narrated situation is an analogy of a programming project without or with a poorly written READme file, that project would not be recognized or noticed by anyone on whatever platform in which you placed your project, for example; GitHub.
WHAT IS A READme FILE?
A READme file is a text file (markdown) that introduces and explains a project, it is like a landing page for most open source projects. It contains information needed to understand what a particular project is all about. A good READme file must be able to communicate to visitors on how to install, how to use, and how other developers can collaborate with you. It is important to note that the READme file tells others to use or contribute to your project so every programming project must have it. READme file is also essential to retrieve a project on Git Hub as well as in search engines, for example; google.
TIME TO CREATE A READme FILE.
It is best to create a READme file along with creating your repo on GitHub for it to be the first file to be created on your project.
STEP BY STEP WAYS OF CREATING A READme FILE.
- Navigate to your GitHub platform.
- Click plus icon on the top right-hand side and select the 'New Repository'.
- In the repository name section, type your repository name.
- Click the checkbox with ' Initialize this repository with a README '
- Click ' Create repository ' button.
- Then your repository is created with a READme file.
Screenshot of how to create a READme file on GitHub
If you forgot to create your READme file with your Repo creation, you can create it on your code editor terminal;
- Change directory (cd) to your project folder on the terminal.
- Type ' touch ' keyword with READme on the terminal.
- READme file is created.
Screenshot of how to create READme file on the terminal
Whichever way you chose in creating your READme file it must be properly written and completed before showing your project to other people or make it public.
INGREDIENTS OF A GOOD READme FILE.
Title: A READme file title should concisely explain what you have in the project and must be related to the content.
Introduction/Summary: This is about two or three sentences explaining what the project is all about and who it is meant for.
Screenshot: This is necessary to allow visitor(s) to have the first feel of how your project looks like before opening your repo files.
Prerequisites: This can be any prerequisite knowledge, tools, or technologies anyone who wants to use the project might need before they begin. For example; Ruby language, you can instruct them to install ruby.
Guide on Installation: This should be step by step process on how to install it if the installation is necessary.
How to use the project: Once the installation has been completed this step should also explain how to use the project with examples and references explaining the command options and flags.
Live demo: A good READme file must contain live-demo and video(optional) links for visitors to check and watch.
Contribution: This should explain the step(s) to be taken or followed in order to contribute to the project.
The author section: This should include those that contributed to the success of the project, it is a way to make an open-source feels like a team effort and acknowledge everyone who has contributed to it. Do not forget to include their contact information if given permission to disclose that. If it is a solo project put only your contact information there.
Acknowledgment: This is where you acknowledge anyone, organization, or group of people that you have used their work for example; designs, images, or code to achieve success in your own project.
License information: This is where you include the license information if applicable in order to obey the copyright law.
If you also care about making your READme file looks great you can add logos, badges, shields, emojis, and so on.
The screenshot of a typical READme file
Inconclusion, for a project to be visible, easily recognized on flatform(s), and also for the purpose of search engine optimization such a project must have a well-written READme file. Henceforth, do not forget to include the READme file in your programming project.