Tips to create a README on GitHub

Photo by Patrick Tomasso on Unsplash

Every project should be introduced in a README. As I am in the process of writing READMEs, I looked around and found some helpful resources that I decided to share in this blog.

1. README content

As a beginner in coding, I found this template really useful. Depending on the nature of your project, you might need to add or remove sections for your own README.

It’s also common practice to record an overview of your application and include it as a GIF in your README.

GitHub also provided the following advice to nail your README:

• Assume you are reading your README for the first time.
• Assume you know nothing about the project, the language it’s written in, the dependencies, the intended audience, the features and benefits you provide, the history of the project, the people involved, and the monetization.
• Assume you have never seen your work at work — provide a graphic and/or link directly to an online working version
• Assume people want to use your work — provide links to your license
• Assume you are also wildly popular

2. README formatting

Make your README more readable by formatting it. There are many techniques you can use to format your README. Here are the ones I believe are essential:

• Heading

Add # in front of the text you would like to render as a header

# The largest heading
## The second largest heading
### The smallest heading

• Styling text

Screenshot from Github help documentation

• Code blocks

Create a code block by adding three backticks ``` before and after your code. (It also works on Medium!)

This is a code block

• Add a link

Add the text to click on, wrapped in square brackets, followed by the URL in parenthesis:

The Track Finder was built with React front end and is connected to the [SoundCloud API](https://developers.soundcloud.com/docs/api)

Output on the README:

Screenshot of a README with a link

• Add a GIF

To add a GIF, save the GIF in the root folder of your repository (same folder as the README.md file) and add the below in the README:

![](gif-name.gif)

Find the full GitHub documentation to format your README here.

Thanks for reading my blog. Please share your tips or resources you found helpful to write READMEs.

Happy coding!