README Files and Directories

Like we’ve talked about, README files are text-based files used in documentation. Files ending in a .md file extension are Markdown files, so a README.md is a README file written in Markdown.

Here’s a good reference guide:

  • What - A README explains the contents of a directory.
  • When - A README should be the first file you create!
  • Where - A README should be top-level (inside the “main” folder).

Markdown README files are only ever named README.md or readme.md!

Services such as GitHub and Bitbucket actually “look” for these files and render them automatically, so it’s important to create these files thoughtfully.

Assignment Reports

Every repository you create for this class, including your weekly assignment repositories, must include a README.md file. Please be sure to add a README.md to each repository.

Directory Tree 
.
├──  assignment-01/
│   └──  README.md
├──  assignment-02/
│   └──  README.md
├──  assignment-03/
│   └──  README.md
... etc ...
└──  README.md Root Repo's README

For every assignment you submit, you will also write a short report in a text file. This report is the README.md for that directory, and may discuss a number of things every week:

  • Questions regarding your understanding of the Topic’s materials.
  • Summarizing the work you did this cycle, paying particular attention to the individual choices you made.
  • Is there anything in particular you learned that you would like to discuss further?
  • What problems did you have? How did you solve them?

development directory markdown readme