Read this document before you start working on the README template.
Note: As your project evolves and grows, so should your README file. READMEs should be revisited regularly to ensure relevant information is captured for new users.
READMes are the first document users find and read. All projects include a README, and users will expect to find one in your project's root folder. A README tells users what they need to know about your project, if the project is relevant to the user, and how users can engage with the project. Your README is your project's first impression.
In some cases, larger projects may include sub-READMEs, or separate, smaller READMEs that support subfolders in the project.
The following sections provide guidance and context on how to fill out the README template.
This section is optional.
A project logo can be helpful for users to visually identify your project.
Embed relevant badges to your README to add credibility to your project. Badges highlight important information and can help users determine project fit quickly. Learn more about badges.
The project name should be prominent in the README and easy for users to identify. You may want to consider adding the following to help identify the project:
- Project URL
- Name(s) of project owner(s)
Note: Consider the stage your project is at. Names associated with the project may be better situated in a separate contact document.
This section is optional.
A table of contents can be useful in the case of lengthy READMEs. As the project evolves, the README may eventually require a table of contents for information organization.
Note: For Markdown files, GitHub now automatically generates a table of contents in the file Header. Learn more here.
The project description is the most critical part of your README. Describe what the project does, why the reader should care about your project, and how it can help the reader. This section should be succinct, use strong verbs, and help the reader determine whether the project is of use to them.
Screenshots or videos may also be included in this section to help readers understand your project. Any assets you direct users to should exist in the repo.
You can use the below project description format to start filling in your section. An example is provided.
With (this project) you can (verb) (noun)...
(This project) helps you (verb) (noun)....
Unlike (alternative), )this project) (verb) (noun)...
Example: With the Chronologue project, you can discover astronomical events throughout documented history. This project helps you understand the evolution of space in a streamlined format. Unlike googling and searching for important astronomical events, the Chronologue project outlines historical events with an easy to use and simple interface.
Identify your project audience and state who can use the project and under what terms.
List any pre-requisites a user needs to interact with your project. Include relevant links to installation instructions or resources.
Describe in clear steps how to get, install, configure, run, and troubleshoot the project. Use a table for troubleshooting common issues to clearly identify issues and solutions.
Provide additional documentation for users by including links and brief descriptions. Examples of additional documentation include:
- Project website
- Twitter handle(s) of project/project owner(s)
- Relevant examples
- Next steps
- Features planned
- Known bugs
- Documentation files
- Help command(s)
Provide guidance for users seeking assistance by including links and brief descriptions. Examples of help resources include:
- Google group/mailing list
- Email address(es)
- IRC, Slack, or Discord channels
- Bug trackers
- Stack overflow
While most projects will have a separate contributing guidelines document, you can provide clear instructions on how users can contribute to the project in your README. A Good Docs contributing guidelines template is available here [LINK TO KAYLA'S TEMPLATE].
The Terms of use section should include your project license and other licensing information, if required.
- Daniel Beck's README checklist
- Daniel Beck's Write the Docs "Write the Readable README" presentation
If there are other README resources you think can be linked in this guide, please open an issue to let us know!