DEV Community

Cover image for How to Document your repository in GitHub?
Taimoor Sattar
Taimoor Sattar

Posted on • Originally published at

How to Document your repository in GitHub?

Documentation of your repo will help you in many aspects. When you link your repo to the hiring team, they will better understand what your code is doing. Also, it will help others to contribute to your project. To write documentation for your repo, you can create in the root of the repo. reads as a markdown file. I have also written details articles about Markdown Get Started Guide. Markdown does not give you whole lot control over the styling of the page. For example, center the image, adjust the width and height, etc. Additionally, you can also write HTML (inline-CSS) in the file as shown below:

<div align="center">
  <img alt="logo" src="/image.png" width="200px">
  <h1>Your headline</h1>
Enter fullscreen mode Exit fullscreen mode

What information to include in

It all depends on your project. It is how you explain what the project is all about. But I have listed out some point that you can list in your documentation repo:

- Include Photo or logo
- How it Works
- Getting started.
- Prerequisites
- How to contribute (Write
- Information about team
- Related Project
- Contributors, Backers, or Sponsors.
- License
Enter fullscreen mode Exit fullscreen mode

Add Table of Content (TOC)

If your file has a long length, then it's better to add table of content. You can add a table of content like this below:

- [How it Works](#how-it-works)
- [Getting started](#get-started)
- [Contributing](#contributing)
- [Core team](#core-team)
- [License](#license)
Enter fullscreen mode Exit fullscreen mode

Clicking the TOC link will scroll to the desire section.

## How it Works
your explanation...

## Getting started](#get-started)
your explanation...

## [Contributing](#contributing)
your explanation...

## [Core team](#core-team)
your explanation...

## [License](#license)
your explanation...
Enter fullscreen mode Exit fullscreen mode

Create Badge/shields

Batches/shields look nicer as it adds information on your repo. Batches/Shields are small block legible badges in SVG and raster format, which can be included in GitHub readmes or any other web page. You can check the status of repo like code size, commit status, or deployments, etc. You can look at how these Badges look on the repo.

Badge/shields GitHub

How you can add these badges

If you use Netlify to deploy your code; you get a badge on their dashboard which shows deploys status. and codetriage are also good resources to add badges for your repo. you can add in as shown below:

<img src="" alt="GitHub Code Size in Bytes">
Enter fullscreen mode Exit fullscreen mode

further structure your documentation describes the basic information about the repo. If your information is long enough to fit into, you can make further sections. For example, and Write how to contribute to this repo in the and code of conduct in In this way, you can be more organized.

Your documentation should be grammatically correct so it is properly understood by others. You can check grammatical mistakes using tools like hemingwayapp and grammarly.

Show some love if you like this article. Follow me on twitter @taimoorsattar7 as I post frequently.

Discussion (4)

geraldew profile image

Very glad to see you including "prerequisites" as something to always have in a README. I'd also suggest adding something about clearly stating the implementation programming language. As someone who works in a very constrained environment, the requirement to install any extra interpreter/compiler immediately rules out a candidate codebase.

Thus for every single project I look at, the first thing I need to be sure about is "what is this written in?" You would think that is very easy to just state in the README and yet this is rarely done.

taimoorsattar7 profile image
Taimoor Sattar Author

It is good practice to mention prerequisites in README.

geraldew profile image

I frequently see various "prerequisites" quoted with no mention at all of the language(s) the code is written in. Sorry if I didn't make that clear.

burdettelamar profile image
Burdette Lamar

You may be interested in the page TOC feature in my Ruby gem markdown_helper.

The gem has a CLI (as well as an API), so no Ruby coding is needed. You just need to have Ruby installed.