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 make for this class will have a README.md file. We initiated our web-dev-hw/ root repository with a README.md file, but all homework repositories will need to have README.md files created for them.

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