Create a README
What is a README ?
A README file is a text file that contains a summery of an introduction and the process about a project (App, Software or game). README files normally include information about:
- What the project does
- Why the project is useful
- How users can get started with the project
- Where users can get help with your project
- Who contributes to the project
Why should we create README ?
Since it is the best way to give an introduction for tech and non-tech people, we should create a README file .
What are the types of README ?
README file could be a simple plain text, READ.ME, README.TXT or README.md.
How should we create README ?
The most common and popular README file type is the README.md. MD files are saved on plain text format that uses Markdown language which also includes inline text symbols, defining how a text can be formatted such as indentations, table formatting, fonts, headers and links.
We can use any text editor to create README.md file such as Visual Studio Code, Atom, Sublime Text, etc…
The below image shows the Markdown input and the way it looks like after rendered it. This is a sample image to show how .md file looks like.
Let’s write a good README…
- Project Name
- Project Description- A short summery about the project and shouldn’t be much longer. Should mention about the background, features, technologies and a link if the project is already hosted.
- Installation- Mention the steps to install the project and/or any dependencies that needed to be installed before project runs. Moreover, don’t forget to mention if there is any requirements (hardware requirements) to run the project.
- Illustration- This part depends with what you have built. You can add a logo, diagrams, some screenshots or a video to give a much comfortable with this app.
- Support- Mention a chat room (Discord, Slack, …) or contact details to contact if someone needs any help relating the projects or programming languages.
- Contribution- Mention the people who supported to build this project and how they contribute to the project. Furthermore, you can mention about the sources that inspired and learned.
- Authors & Acknowledgment- Information about author and thankful for them to guidance and support they have given.
- License- Mention the license type or details.
Guo D (2021) Make a README, https://www.makeareadme.com, accessed 9 February 2021.
GitHub (2021) About READMEs, https://docs.github.com, accessed 9 February 2021.
Aspose (2021) Word Processing File Formats, https://docs.fileformat.com, accessed 9 February 2021.
