Include a README with your project

What is a README? #

This is a file that is named README, that usually resides in the root of your project directory. This name comes from the command Read me. as in the situation of handing a project off to another developer and writing a memo to them that should be read first before the source code.

In a way, it serves as an executive summary of your project. It gives your reader a chance to understand what’s going on since source code doesn’t describe the intent and purpose of projects very well.

What should go into a README? #

The readme should contain description about what the project is about, and also information to build and/or run your program.

An example of a barebones README can be found at https://github.com/cisc3130-s20/assignment-template

Within this file it starts with the title of the project, followed by instructions for setting up a development environment and then some info on where code can be saved.

There’s generally no industry standard on the order sections should go or how to name the sections. It’s generally based on what makes sense to you, and/or what you think would help your reader.

Formatting a README #

This file is usually a text file. It can be written in plain text, however you can also choose to use some sort of formatting if you’re publishing your project on GitHub and the like. That formatting is called markdown - it is a way to help your text be more readable on the web page.

For example, if you want to add a title to your markdown you can use a single # symbol to mark it as a heading level 1 (top level). You can add inline code snippets using the ` character or a code block with three ticks as fences around the section.

The other formatting possibilities like bold and italics is a lot like formatting chat messages in discord and slack, with a mixture of _, *, ~ symbols to mean varoius things. Take a look at the markdown page for more guidance.

Read more about READMEs #