8.7

Read Me

don't

Add a README.md file to the project directory. The first item in the file explains the overall purpose of the project. Extend the file with each weekly assignments to record your progress.

They do say that the best way to keep a secret on a computer is to place it in a file named README.

In general, use the README.md to
  • state purpose of each folder and file in the directory;

  • sketch a roadmap base so that new maintainers can figure out how to navigate the repository. You may wish to use diagrams for this task to explain the relationship among the pieces, their interactions, etc;

  • demonstrate how to run the test harness for each milestone;

  • explain how to run the complete set of internal unit tests and the individual ones.

The goal is to enable future maintainers to rapidly find their way around the code base, add unit tests for new bugs, fix a bug, or even add a feature—without necessarily understanding the complete code base.

If you haven’t seen any good examples, take a look at these.