These slides are adapted from the MEDS README Guidelines (mostly because it helps me stay on track while teaching ). Please be sure to reference the “official” guidelines document when you return to these in the future.
GitHub makes this easy! Check the “Add a README file” box each time you create a repo on GitHub:
If you’re creating a repo locally first, add a README to your project’s root directory using the command, touch README.md (in the Terminal), or click New File > Text File > type README.md > OK (in RStudio’s Files pane).
What you include in a given README will look different depending on the project.
But there are some guidelines you should follow…
A README’s title is set to the repository name by default - change this!
By default, this README title was strava-dashboard (the name of the repo) – here, I’ve updated it to something a bit more descriptive.
Paragraphs or a bulleted list are both acceptable options. You may also include an image or logo that represents the project.
In this example, I include a bulleted list that describes the (personal and professional) motivations for this project.
This includes information about the repository structure or file organization.
A repo “map” of the folder structure and important / necessary files for making this shiny app run.
Open and close a code block with three backticks at the start and end. Use the pipe, |, along with these (somewhat odd) characters, ├── & └──, to construct a folder / file map of your repo.
This is also a reminder to create an intuitive folder structure within your repository! Reorganize files as needed / appropriate. Here’s one example of an intuitive repo structure – this will vary depending on your project:
Any necessary information on where data lives (e.g. is it housed in the repo, on a server, in a library / package etc.) and how to access it in order to run the code
Information on what tools (i.e. {rStrava}) I used to scrape my data, where that data retrieval / wrangling occurs, and where I save my cleaned data to. Also note that I mention a wiki – more on that soon.
Consider hyperlinking collaborators’ GitHub profiles or other professional profile
A not totally necessary contributors section (I’m the only contributor, so far).
Add references in an appropriate, consistent format (including links). Don’t forget to add references for data sets too!
My acknowledgements section includes links to a variety of blog posts, articles, and software that I referenced / used while building my dashboard. It also, importantly (though not at all necessary), includes a pup pic.
From GitHub Docs:
“You can use your repository’s wiki to share long-form content about your project, such as how to use it, how you designed it, or its core principles”
- move any documentation-style info from your README to a wiki, as appropriate
- you can link to wiki pages from your README
- each wiki page should focus on a single topic
- add a wiki by clicking Wiki > Create the first page (creates landing page) > then add additional pages
READMEs aren’t just for repositories – we can create account-level READMEs to introduce individual users or organizations:
A GitHub profile README
A organization README
