How to make the perfect Readme.md on GitHub

GitHub, A very common name on the world of developers, is the largest community of developers to share, discover and build better software. From reading awesome documentation to web-based hosting service under version control, GitHub can do everything.

Photo by rawpixel.com from Pexels

From providing access control and several collaboration features such as bug tracking, feature requests, task management, and wikis for every project, we all know how cool GitHub really is. But let’s face it, even if you have the generation’s best project lying down in your profile, without an attractive and a detailed readme, it gets unnoticed.

Every time when you create a repository on GitHub there are two options at the bottom.

1. Add a readme — This creates a default readme with just a basic description.
2. Add a license — This has a variety of licenses to choose from depending on the type of software you are making.

So what is this Readme.md file?

A Readme file gives the user(who visits your repository) a brief idea about what the project is about, which language it has used, what are the terms and conditions, licensing, how many forks/stars the repository has got, what your project can do, screenshots of your running application, etc

The extension .md stands for Markdown which is a lightweight markup language with plain text formatting syntax. It’s a very simple language used to create beautiful and presentable readme files for GitHub.

How should you write it?

You need to follow a certain syntax pattern to get the correct Markdown script as your desired output.

Header

# H1
## H2
### H3
#### H4
##### H5
###### H6

Alternatively, for H1 and H2, an underline-ish style:

Alt-H1
======

Alt-H2
------

Emphasis

Emphasis, aka italics, with *asterisks* or _underscores_.

Strong emphasis, aka bold, with **asterisks** or __underscores__.

Combined emphasis with **asterisks and _underscores_**.

Strikethrough uses two tildes. ~~Scratch this.~~

Lists

1. First ordered list item
2. Another item
⋅⋅* Unordered sub-list. 
1. Actual numbers don't matter, just that it's a number
⋅⋅1. Ordered sub-list
4. And another item.

⋅⋅⋅You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).

⋅⋅⋅To have a line break without a paragraph, you will need to use two trailing spaces.⋅⋅
⋅⋅⋅Note that this line is separate, but within the same paragraph.⋅⋅
⋅⋅⋅(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)

* Unordered list can use asterisks
- Or minuses
+ Or pluses

Links

[I'm an inline-style link](https://www.google.com)

[I'm an inline-style link with title](https://www.google.com "Google's Homepage")

[I'm a reference-style link][Arbitrary case-insensitive reference text]

[I'm a relative reference to a repository file](../blob/master/LICENSE)

[You can use numbers for reference-style link definitions][1]

Or leave it empty and use the [link text itself].

URLs and URLs in angle brackets will automatically get turned into links. 
http://www.example.com or <http://www.example.com> and sometimes 
example.com (but not on Github, for example).

Some text to show that the reference links can follow later.

[arbitrary case-insensitive reference text]: https://www.mozilla.org
[1]: http://slashdot.org
[link text itself]: http://www.reddit.com

Images

Here's our logo (hover to see the title text):

Inline-style: 
![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

Reference-style: 
![alt text][logo]

[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"

Visit this link for in-depth knowledge on how to write a markdown sheet

(All the syntax have been referenced from: Markdown Cheatsheet by Adam Pritchard)

Photo from MarkdownGuide.org

Now that you’ve created a basic readme file, Let’s come to the fun part

Let’s buff up our designing skills and make this readme look catchy and attractive, shall we?

First things first, we’ve already crafted up the descriptions, getting started and the details now it’s time to add some working demonstrations(in the form of gif) as well as screenshots of the product. It may or may not be helpful sometimes, It totally depends on the project you are making.

If it is an app or a website, It’s a better idea to have a prototype out there but if it’s simply a code it doesn’t make sense to have a screenshot right? So think for yourself and do whatever you feel is right for your project.

Inserting Screenshots and gifs

It's always a better idea to show your working prototype side by side rather than putting one image per paragraph, For instance in this project, It's better to have all the images lined up together as in -

Rather than having all the images and gifs standing there one below the other. And also its always better to have gifs since it better expresses your work and also lets the reader know how the application actually looks like from a user’s perspective.

How to put the images side by side?

One approach could be using the <img> tags as used in HTML, where you can set the width and the height of the image to be placed in the readme. It's recommended changing only the width so as to maintain the aspect ratio of the image, else if you want it customized? Feel free to explore with the height as well.

To have multiple images next to each other all you need to do is put them right after you finish writing the markdown of the previous one.

NOTE: Whatever image you choose to have in your readme file, make sure you also have that uploaded in your repository as well. Or you could reference the link address from anywhere, that’d work too.

How to add badges

Badges are a really important part of any GitHub readme as it not just tells you but also the reader how many forks this repository has, how many issues have been raised till now, and also gives away a lot of valuable information for the user to decide whether they’d want to contribute to this repository or not.

Some set of badges I use in a specific repository called ‘Tic Tac Toe’ looks something like this.

Anyone who views these badges automatically gets to know what licensing it has, how many forks or stars this repository has, is it still maintained by the developer and so on.

There are a variety of badges you can create and it also varies from projects to projects on which you want to use for your particular repository.

A simple and easy way to create them is to visit shield.io

HomePage of Shields.io

This is an awesome website which can suggest you badges if you are all new to GitHub and don’t know what badges to use for your repository, not just that, you can also create your custom badges with your own choice of colors, endpoints and whether to keep it dynamic or static.

All you have to do is copy the web address of your GitHub repository and paste it where it says “search/project URL”. After you paste it, there will pop an option which will say “Suggest badges”.

Once you click on that, shields.io analyses your repository and suggests you badges which you can then copy and paste in your readme file wherever you want them to be.

Licensing

This is a vast new topic on the GitHub itself and it’s pretty difficult to know what are the contents of all the license present out there. If you want more in-depth knowledge about the licenses, I’d suggest reading this article.

Licensing a repository - GitHub Help

The three major licenses used are :

1. Apache License v2.0
2. GNU General Public License v3.0
3. MIT License

In most cases, if you’re building an open source product and you want people to distribute as well as contribute to your code, you’ll need the Apache License.

See the Terms & Conditions of Apache License HERE

To implement Apache License v2.0 in your readme as well as your repository, Type the following in your readme file.

Copyright [yyyy] [name of copyright owner]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

NOTE: Whatever license you choose, always read the Terms very carefully since they contain the right to your software.

Last but not the least, Thank you for reading this, Since I’m a beginner and I may make mistakes, feel free to point it out so that I can rectify them along the way.

Peace Out.