_edited_edited.png)
What?
A README is a text file that introduces and explains a project you have worked on. It contains information that is required to understand what the project is about and sometimes the instructions that need to be followed to proceed further.
The default readme file contains the repository name and some basic instructions. The file format is ‘md’, which stands for Markdown documentation. It is a lightweight markup language that can be easily converted to text.
Why?
A readme file is an excellent way to document effectively and communicate efficiently with your team. While working on projects and hackathons along with handling kids and other household work we find it often difficult to schedule a meeting every time our team needs help. A well-prepared readme file provides a solution to navigate such situations with ease.
Significance of readme file:
Simplifies your design and Implementation to a reader or viewer.
You can present your work through flowcharts, which can help explaining the complex functionalities of your project to other team member or any other viewer.
You can document reference URL for future use, if you are working in more than one project and come back to previous project after a while, a readme file can help you recall the work flow of the project.
You can use images as a verification source for the intended outcomes.
A well-written readme file is also important if you intend to show your projects in your resume. The interviewer might go to your project but might not understand a single piece of code. But if there is a readme file, it will help user to understand better what the project is for, which coding languages/frameworks were used and how to navigate through that project.
How to create a readme file?
1. Go to Your project folder --> right click --> new ---> file
2. To create a readme file "Name" of the file will be followed by the extension ".md"
3. Once created, you can see the readme file under the project name.
How to write in a readme file?
I have tried to cover the insertion of a few basic components like headers, flowcharts, tables, url, and pictures in this blog. However the list is long and you can add a few more, or complex structures like class diagrams, ER diagrams, pie charts, requirement diagrams, and context diagrams.
1. Headers: Marked with #.
# - Header 1
##- Header 2
###### - Header 6
example:
2. Font Style: Marked with * or _
*Italics* OR _Italics_: use a single star before and after the word or sentence to write in italics.
**Bold** OR __bOLD__: use two stars before and after the word or sentence to write in bold.
Note: Both styles can also be combined
examples as shown in the image:
3. Flowcharts: Marked by ` (backtick)
a. To create flowcharts click backtick (`) thrice followed by the word "mermaid"
b. Press enter, write "flowchart" in the next line
c. you can add headings and subheadings in the flowchart as shown in the image below
4. Tables: Marked by '|'
a. You can add tables to the readme file starting with your headers in between two pipe (|) symbols.
b. followed by a row of dashes within the pipe symbols to create a distinction between headers and contents of the cells.
c. contents of the cells should also be specified in between two pipe symbols in the next row as shown below
5. Images: Marked By '!'
To insert an image insert '!' followed by [alt text] and the image path in the readme.
example:
6. URL: Any url pasted in the readme file will be a working link upon insertion in the readme file.
To connect the link to a particular text you can follow the syntax [text] (URL link). It will be appeared as shown in the picture below.
Signing off in the hope that this little piece of information can be of some help to all the Numpy Mummies, as it helped me during my project. Wish you all a wonderful learning Journey!!!