Lesson Monday

Every GitHub repository should include a README.md file that provides any visitor to the repository with detailed information about the project. READMEs are called READMEs because they scream to the user "READ ME!". The READMEs we will write have the extension .md which indicates that they are written in the Markdown language. Like HTML, Markdown is a language that uses marking annotation to format text for display. Markdown is for simple documentation like a README file. For reference and resources, visit the cheat sheet for this lesson.

Location

The README.md file should always be stored at the top level of the project folder. GitHub will look for this file and present it on the main viewing page of the repository.

Content

READMEs vary widely from one repository to the next. Epicodus recommends including as a minimum the following sections:

  • Application name
  • Names of contributors
  • Description of the project's purpose
  • Complete setup/installation instructions
  • License information with a copyright and date

Additional sections to consider:

  • Technologies used
  • Known bugs
  • Contact information
  • Support or contribution instructions

README Template

Here is an example README from an Epicodus project:

Epicodus README sample

It's worth taking the time to make your README look nice because it will be the first thing anyone will see in your repositories. If people see that you have a messy or incomplete README, they will assume that your code is also messy or incomplete. But if you have a README with clean formatting and clear setup instructions, your users will have more confidence in trying out your software (and in trying out you, if they're an employer looking to hire!).

Below is a README sample template written in Markdown. You can copy and paste the text below into a new file and replace the relevant parts that are mentioned in curly brackets with information about your project. Don't include curlies in your readme, replace the content instead. All of the sections from above are included but you can add and delete to make your README look the way you want it to.


# _{Application Name}_

#### _{Brief description of application}, {Date of current version}_

#### By _**{List of contributors}**_

## Description

_{This is a detailed description of your application. Its purpose and usage.  Give as much detail as needed to explain what the application does, and any other information you want users or other developers to have. }_

## Setup/Installation Requirements

* _This is a great place_
* _to list setup instructions_
* _in a simple_
* _easy-to-understand_
* _format_

_{Leave nothing to chance! You want it to be easy for potential users, employers and collaborators to run your app. Do I need to run a server? How should I set up my databases? Is there other code this app depends on?}_

## Known Bugs

_{Are there issues that have not yet been resolved that you want to let users know you know?  Outline any issues that would impact use of your application.  Share any workarounds that are in place. }_

## Support and contact details

_{Let people know what to do if they run into any issues or have questions, ideas or concerns.  Encourage them to contact you or make a contribution to the code.}_

## Technologies Used

_{Tell me about the languages and tools you used to create this app. Assume that I know you probably used HTML and CSS. If you did something really cool using only HTML, point that out.}_

### License

*{Determine the license under which this application can be used.  See below for more details on licensing.}*

Copyright (c) 2016 **_{List of contributors or company name}_**

Licensing

An open source license details how others can use your code. MIT and GPL are the most common licenses. An MIT license means your code is free to use by anyone and you are not liable (Rails and jQuery use an MIT license). GPL also indicates free usage of the code but when used, the resulting work MUST be open source (Linux, Git and Wordpress use GPL).

For additional details on choosing a license for your code, visit GitHub's Choose a License site.

Expectations

Moving forward, you're expected to include a detailed README.md file for every project you create here at Epicodus. This ensures that anyone who views your portfolios (ie: potential employers!) can quickly understand the concepts you've practiced, and the breadth of apps you've created!

In fact, in level 3 courses all students spend a full day preparing materials for internship interviews, and their future job search. In addition to writing cover letters, preparing a LinkedIn profile, and practicing interview questions, students are also required to ensure all their GitHub repos have detailed READMEs, as seen in this level 3 assignment. Make sure to create a README for each project now, so you don't have to go back and add them all later.

Terminology


  • README: A file located in a project's repository that provides detailed information about a project.

  • Markdown: A simple language that uses marking annotation to format text for display in a browser.

  • Open source: Software that is freely distributed by its creator(s) for use and distribution.

Examples


Headers

Headers are designated with a #. Text with 1 # is the largest and text with 6 #s is the smallest.

# Best Chocolate Chip Cookies
## Best Chocolate Chip Cookies
### Best Chocolate Chip Cookies
#### Best Chocolate Chip Cookies
##### Best Chocolate Chip Cookies
###### Best Chocolate Chip Cookies

becomes

Best Chocolate Chip Cookies

Best Chocolate Chip Cookies

Best Chocolate Chip Cookies

Best Chocolate Chip Cookies

Best Chocolate Chip Cookies
Best Chocolate Chip Cookies

Italics

To create italics, surround the text with single underscores _.

Example:
_Be warned_, these will fly off of the plate!

becomes:

Be warned, these will fly off the plate!

Bold

To create a bold text, surround the text with double asterisks **.

Example: Bake for **10 minutes** or until golden brown.

becomes:

Bake for 10 minutes or until golden brown.

Ordered lists (numbered)

Ordered list just use the number and period for each line.

1. Beat the butter...
2. Mix the flour...

Unordered lists (bullet points)

Bullet points are made with the * and a single space. There must also be a blank line before the first item on the list.

Example:

Ingredients

* butter
* flour
* brown sugar
* maple syrup

becomes:

Ingredients

  • butter
  • flour
  • brown sugar
  • maple syrup

Links

Two elements make up a Markdown link, the text that will display on the page surrounded by [] and the web address where the link will go surrounded by ().

Example: [Click here](http://allrecipes.com/) to check out my other great recipes.

Images

Like links except the square brackets are preceded by ! and contain alt text for the visually impaired, and the () can contain a web address for an image.

Example: ![An image of a cookie](http://lorempixel.com/400/200/)

Additional Resources


For more on Markdown: Daring Fireball.