Code projects are required to include a README.md file in the root directory of the repository. The README is the front page of the project: it should allow someone who opens the repository to quickly understand what the project does and how to build and run it.

The following requirements apply to any and all courses that use version control for programming work, including courses not primarily focused on programming, unless an assignment specifically states otherwise.

A README should be complete, accurate, and concise. More documentation is not automatically better. Do not add filler simply to make the README longer.

Required Content

Unless an assignment specifies additional requirements, every README.md must contain the following:

1. Project Title
   Give the project a clear title that identifies the software.
   
   
2. Description
   Briefly explain what the program does and its purpose. This should describe the completed project, not simply repeat or copy the assignment instructions.
   
   
3. Requirements
   Identify the language, runtime, compiler, libraries, or other software needed to build or run the project. Examples include Python 3, g++, C++20, or a required external library. If there are no special external dependencies, say so when appropriate.
   
   
4. Build and Run
   Provide the exact command or commands needed to build and run the project. For an interpreted program, this may only require the run command. For a compiled program, include both the build and execution commands.
   
   
5. Usage
   Explain what input the program expects and what output or behavior the user should expect. Include a short example when an example materially helps explain how the program is used.

Standards

• The file must be named README.md and placed in the root directory of the repository.
• README files must use Markdown syntax and should be organized with appropriate headings, lists, code blocks, and other formatting where useful.
• The README must describe the project that was actually submitted. Commands, requirements, examples, and other technical information must be accurate.
• Build and run commands must work in the environment required by the course or assignment.
• Keep the README concise and professional. Do not add unnecessary sections or generic filler simply to make it appear more complete.
• Individual assignments may require additional sections or information when appropriate to the project.
• Generative AI may be used to help create or improve the README when permitted by the course. You remain responsible for verifying that everything in the README accurately describes the software you submitted.

Resources and Examples

The following resources can help with Markdown formatting and README organization:

• Markdown Guide: Basic Syntax
• How to Write a Good README File for Your GitHub Project
• README Rules: Structure, Style, and Pro Tips

You may also look at the following in-class examples for ideas about structure and presentation:

• minicrawler
• weather-snapshotter

These examples are not templates or minimum-length requirements. The appropriate amount of documentation depends on the project. A small program may need only a short, well-organized README, while a larger project may require more detail.