Understanding and Writing a README for Mod 1 Projects

What is a README?

A README is a file that contains the important information about a project. It is called a README because it should be the first file that is opened and should guide the reader in understanding how to use the project. Think of it as an instruction manual for the user. In this case our user is other developers.

Your Mod 1 projects will include a README that is written in Markdown, which is why it has the .md extension. If you want to learn more about Markdown here are some resources to get you started:

• What is Markdown
• Mastering Markdown
• Markdown Cheat Sheet

Why should YOU write a README?

Now that you understand the purpose behind the README, how does it more direclty relate to you. Writing READMEs is an opportunity for you to practice organizing information, writing technical documentation, and reflecting on your project and process. These skills will be essential for interviewing and on the job.

What to include in the README?

For your project READMEs, you should oragnize the information so that it is clear and easy to follow. It should be broken into sections to help the reader more easily understand and find information. Let’s break down what sections you should be including in your Mod 1 README.

• About
  • Should be a breif summary of what is the application.
• Built With
  • Include the Ruby and RSpec version here.
• Getting Started
  • Breakdown the set-up instructions. Start with how to clone down the application and include all the steps necessary to run it locally.
  • Not sure if you missed something? Ask a peer to follow your directions exactly to see if they can run the application.
• Testing
  • Give directions for how to run your tests.
  • Explain how your tests are organized.
  • Provide a summary of the types of tests that you’ve written and why those tests are vaulable to the application.
• Challenges & Wins
  • Reflect on your process and what you have learned in the project.
  • What were the challenges you experienced?
  • How did you overcome them?
  • How will this experience benefit you in future projects?
• Authors (Optional)
  • If you worked in a pair or group, give those partners recognition!
  • Make their name a link to their GitHub Account.

What next?

Now, it is time for you to go write an awesome README!

Feeling extra fancy?

Check out these resources for how to include badges and visual recordings.