What is a README?
A README is a file that gives a broad overview of what is in a directory or repository. If you’re using GitHub, the README shows up on the repository page and is a markdown file (has the suffix .md). A README in a data repository (which you’ve seen on your midterm) is usually a plain text file (.txt).
Why have a README?
You might know how your code and data are organized, but no one else does. By writing an informative README, people can read about the repository and then explore it to find what they’re looking for. You can also write a README for yourself to keep things organized (i.e. understand where you’ve put things so that you can find them again).
It’s an extra little step that future you and anyone else working with your code/data will use to understand how your files are organized and where they come from.
What does a README look like on GitHub?
You can look at this repository to see where the README shows up in a repository. It is one of the first things anyone will see.
You can format your README using headers and subheaders to make it easier to navigate. The button with three lines in the top right of the README will display a table of contents.
What should go in a README?
For this class, any README should have at least:
General information
This is where a general description of the repo would go. This could include (but is not limited to):
- names of people working in the repo
- where the data came from
- broad research questions and analyses to address those questions
Data and file information
This is where a description of the data and files could go. For example, you could describe:
- the data file format, when you accessed the data, etc.
- the different code files and what they contain
A tree diagram displays all the files in your repository in a neat, navigable format for your README. See the repository README for an example.
A tree diagram is not required, but it can be an easier way of outlining your data/file structure than a simple bullet point list.
In the video on Canvas, I make a reference to an additional package you will have to install to generate a tree diagram. Here are the basic directions to install tree if you are using homebrew or otherwise.
Rendered output (specifically for this class, but nice to have in other README files too)
For 193DS assignments, you should put a link to the rendered file here so that it is easy to access.
More information about README files
- UCSB Library Data Service guide to writing a
README
- Cornell Data Service guide to writing “readme” stype metadata
- Matias Singers’s list of awesome READMEs and README 101