–Read Me
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 project milestone to help readers navigate the code base.
The purpose of a README.md file is to help (1) you and (2) newcomers to explain and navigate the code base:
-
you can use it to provide an overview at the beginning of a code walk; and
-
a newcomer can read it to understand the organization of the code base and relationships among files that can’t be written down in plain code and that belong to none of the related files.
The first item in such a file explains the overall purpose of the project or directory.
The second one enumerates all files and the purpose of each file.
The third part explains how to run the internal unit tests and, for the milestone folders, specifies how to run the test harness for each milestone.
The last part explains ideas, concepts, and relationships among files. You may wish to use diagrams (ASCII or scanned-in napkin doodles) for this task to explain the relationship among the pieces, their interactions, etc;
In sum, the goal is to enable future maintainers—including older versions of yourself—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. Some of these might be better fits to future workplace repos.