README
Although the specific content of a README can vary from project to project, several sections are recommended because they address fundamental aspects that are relevant to most projects.
You should ensure that your README addresses the following:
- The purpose of the project is explained.
- You have described how to install, use, and develop the code.
- You have explained the licensing terms for the project.
- Information is provided on how to reach out to you, ask questions, or contribute.
Description
Although explaining the purpose might sound self-explanatory, it is important to clearly explain the motivations and objectives of your project. This section should serve as an introductory overview that informs potential users and contributors about the essence of your project.
Provide background information and include links to any references that someone might not be familiar with. If there are alternatives to your project, this is the place to outline what sets your project apart.
Installation and usage
This section should detail the steps needed to set up the software in their environment.
Before installation, users must be aware of any prerequisites or dependencies required. This can include specific versions of programming languages, libraries, operating systems, and hardware. It is recommended to make use of a dependency manager such as pip or conda for easy and reproducible installation.
After listing the dependencies, describe the installation process step-by-step. This might involve downloading the software from a repository, compiling code, or using a package manager.
Example: The scikit-learn GitHub repository provides a good example of the Installation section of a README.
You can include the simplest possible usage example directly in the README and provide more complex examples in additional files or links.
Example: The TensorFlow GitHub repository gives a small usage sample after installation instructions and provides a link with additional examples and tutorials.
It is recommended to write READMEs in markdown formatting and they should be placed in the top-level directory of your project. It is better that your README is on the side of too much information than too little. If you find your README is becoming too extensive, think about incorporating additional forms of documentation instead of omitting important details.