Skip to main content

How to create README

What is a README and its purpose ?​

A README file is a document that gives important information about a project. It’s usually the first place people look to understand what the project is about and how to use it.

Why a README is Useful in Projects ?​

  1. Quick Overview: Helps users understand what the project does.
  2. Instructions: Provides step-by-step guides on how to install and use it.
  3. Documentation: Serves as a main source of information for the project.
  4. Attractiveness: A good README can encourage others to use or contribute to your project.

Basic Markdown Syntax Examples​

README files are usually written in Markdown (.md), a lightweight markup language that can include plain text, images, links, and code snippets. Markdown is supported by most version control platforms like GitHub, GitLab, and Bitbucket.

Heading

# heading 1
## heading 2
### heading 3
#### heading 4
##### heading 5
###### heading 6

Bold

**Bold**

Italic

*Italic*

Single line Highlight

`highlighted` text


Multi line Highlight

```Multi line highlight
   in markdown

```;

Image

![Project Logo](https://example.com/logo.png)

Links

[Link Text](https://example.com)


List

**Lists**

1. Ordered item 1
2. Ordered item 2
3. Ordered item 3

- Unordered item 1
- Unordered item 2

Horizontal line

---

Want to watch tutorial for more ..

Click here to watch

Steps to Add a README to Your Project

In the root directory of your project, create a file named README.md.

screenshot-1

Best Practices for Structuring the README​

  1. Project Title and Badges: Include the project name, logo (if available), and badges like build status or license type.
  2. Table of Contents: Include a TOC for easy navigation, especially for longer READMEs.
  3. Introduction: Clearly describe the project, its goals, and the problem it solves.
  4. Installation: Provide clear steps on how to install or set up the project, including any dependencies or prerequisites.
  5. Usage: Include examples and code snippets to demonstrate how to use the project.
  6. Contributing: Explain how others can contribute to the project, including coding standards, branch policies, or issue reporting guidelines.

Additional Points to Include in a README​

  1. Prerequisites: Mention any tools or environments required before setting up the project (e.g., Python 3.8+, Node.js).
  2. Known Issues: A section listing any known bugs or issues, along with possible workarounds.
  3. Changelog: A brief changelog indicating major updates or releases.
  4. Contact Information: Add ways to reach out for support or collaboration (e.g., emails, social media links).