Creating an Effective README.md for GitHub Project


(Burdette) #1

I’ve run into this wonderful post, which is mostly about creating an effective README.md page for a GitHub project.

So, Automation People, what other tips can you share? (You do have GitHub projects, right?)


(Paul) #2

My tip of the day - Formatting is important. Learn how to use bullet points, headings and tables.


(Burdette) #3

I’ve conjured up a few more tips, mostly to do with linking.


(Vishal Dutt) #4

Why README is important for GitHub project:

Open source community is one of the fastest growing community. Developers release new open source projects with code on GitHub repository everyday. Hence, it is becoming more difficult to get your project to get attention from developers. However, you can follow some approach to increase your chances of grabbing other developer’s attention. One effective technique is to create nice-looking README.md file for your project. Your README file should be effective in way to make first hand impression. Without README file, developer may not look at your project, because developers have no idea what have you built.

Now, you know importance of README file. It is easy to write by following below approach. Here are some of the points you need to take care while writing README file:

Project Title:
A little information about the project. For Example: Automation framework for ‘Mobile Application testing’ etc.

Motivation:
Provide description of reason behind the creation of project. How it will be helpful for others.

Build Status:
Provide Build status of project as per result on Continuous Integration tool like Jenkins.

Code Style:
Here you need to provide the Code style being used in your project. It will help others to contribute in the same format. For example, Code Style: Standard.

Screenshot
Add some screenshots for Logo or home page of site (if any).

Technology/Framework Used: Provide here Technology and Framework is used in your project. For Example:

Technology Used : Java, TestNG, Selenium, Maven
Framework Used: Page Object Model

Features:
Here you need to add features of your project. For Example: This project will help Automation Testing Companies to test their application using automation to reduce the manual time.

Code Example:
Provide a short and concise example of your code in this section.

Installation:
Here you need to provide the steps to get the project running.

API Reference:
Add the reference of API which you have used in your project.

Tests:
Provide example how to run the code. For Example: How to run the script for mobile application.

How to use:
Include steps to provide details about how to use your project.

Contribute:
Provide the description about what people can add in your project.

Credits:
Provide links to the repository which inspired you to develop project.

License:
A short description about the license.

Formatting of README file:

Formatting is important for your README file. Please look into the below points:

  • Add 1 to 6 ‘#’ sign before Heading and keep it same for all heading.
  • Keep the heading bold by adding ** at the start and end of the heading.
  • Add * symbol at the start and end of the text to make it italic.
  • You can quote the text by adding ‘>’ symbol at the start of sentence.
  • You can call out a command with single backticks symbols by adding it at the start and end of the command.
  • Add Links:
    Add a text in square brackets and then put link in parenthesis.
    Example: [GitHib](https://www.github.com)
  • Add bullet icons for list items:
    Add - or * at the start of list items.
  • Tasks List:
    Add [] at the start of item to make it pending and add [*] to make it completed. It will be displayed as checked check box.
  • Mention a person or organization by adding ‘@’ before his name similar to Facebook.

Hope this information is helpful for you.