Make Your Github Project Easy (For Others) to Setup

When you are working on a project, it's tempting to jump in and immediately start to code, but what about others that need to know how to setup and get your codebase running?

This could be your coding bootcamp instructor that needs to help you troubleshoot, someone that wants to contribute via an open source workflow, or an Engineering Manager that is considering your job application to their team.

If you're not sure what makes a good Github README, don't worry. I got you!

Here are some sections to include and helpful info to help you beef up your README and showcase your project to the world!

1. Title (H1)

We don't want to skip over the project title as this sets the tone and helps folks understand what the project is all about. Especially for major portfolio pieces name your project, but make sure to update the title formatting in the README.

2. Project Description (H2)

(paragraph) Give a brief summary of the project and the purpose of the application.

3. Feature List (H3)

(checkboxes) List out the desired features for the application. You can distinguish between a list of MVP Features and Stretch Goals if you want to add more details. I like to use checkboxes for this list in markdown since you can edit them to show as completed as you finish features.

4. Project Setup

The various sections describe how someone can get the project up and running locally. One crucial area is to make sure you cover hidden dependencies such as environment variables that your code includes.

You can describe the environment variables and file name needed in this section, but it is a bonus if you include a .sample file to show the exact setup. For example if you use the dotenv library in your application, your .env file should be under your .gitignore, however, you can have a .env.sample file that is committed and shows how the .env should be formatted.

It is also helpful to include ordered setup commands which can be displayed using code blocks. If you include the language, then syntax highlighting can be included as well.

5. Backend Endpoints

Especially for backend or API projects, include a detailed record of the endpoints available along with the associated ACTION, VERB, and DESCRIPTION of what the request is used for. Although this can be found by reading your code, you'll do your repository visitor a huge favor by outlining these explicitly. If your repo is a developer tool, this is a crucial part of documentation for your users!

Wrap-up

Outside of the README.md file, be sure to complete your repo metadata by completing the Description, Website (url), and Topics under the About section for the project.

Get creative by jazzing up your README with images such as a custom logo for your open source project as well as in-app screenshots (I'm looking at you CSS gurus 👀)!

By no means is this an exhaustive list, however, these elements will definitely set the tone for visitors to your repository and help your project shine!

Let us know what other elements you think are essential in a good Github README in the comments below. Feel free to share other questions you have that I can cover in more detail here, another blog, or a YouTube video or live workshop.

Enjoy the sample README.md. contents below.

Happy Coding! 👩🏽‍💻😸

# Project Title


## Project Overview

### Description

Here is a description of the project and the purpose of the application


### Team Members

- [Team Member 1](http://github.com/<team-member-1-profile>): Role
- [Team Member 2](http://github.com/<team-member-1-profile>): Role
- [Team Member 3](http://github.com/<team-member-1-profile>): Role
- [Team Member 4](http://github.com/<team-member-1-profile>): Role


### Feature List

#### MVP

-[ X ] Completed Feature 1
-[ ] Feature 2
-[ ] Feature 3
-[ ] Feature 4
-[ ] Feature 5
-[ ] Feature 6

#### Stretch Goals

-[ ] Feature 7
-[ ] Feature 8

## Project Setup

### Tech Stack

- Language
- Library
- Framework
- Database
- ETC...

### Requirements

.env file instructions and any other prerequisite tools needed

### Installation Instructions

```
shell

<include commands in order of execution to setup and run the project>

```

### Associated Repos

Make sure you reference  and [link](https://github.com/<username>/<associated-project>) to other repositories needed to setup your entire project such as the corresponding frontend or backend repo.

## Endpoints

Document your backend endpoints if needed

| Action  | Verb   | Route       | Form Action | Description |
| ------- | ------ | ----------- | ----------- | ----------- |
| INDEX   | GET    | /<resource> | index.jsx   | A list of all the <resource> |
| SHOW    | GET    | /<resource>/:id | show.jsx | A detailed view of one <resource> |
| CREATE  | POST   | /<resource> | none | Create a new <resource> |
| NEW     | GET    | /<resource>/new | new.jsx | A form to create a new <resource> |
| EDIT    | GET    | /<resource>/:id/edit | edit.jsx | A form to update the <resource> |
| UPDATE  | PUT    | /<resource> | Update the <resource>
| DESTROY | DELETE | /<resource>/:id | delete.jsx | Delete the <resource> |