Please see the source of this guide in the template repository.
README template guide
Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our templates GitLab repository.
Why do I need a README?
Your README is your project's first impression and the first document users expect to find in a 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.
In some cases, large projects may include sub-READMEs, or separate, smaller READMEs that support subfolders in the project.
As projects evolve and grow, so should the according README file. READMEs should be revisited regularly to ensure relevant information is captured for new users.
README best practices
- Write your README in an approachable, friendly voice.
- Use strong verbs to describe your project, such as "instruct," "discover," or "build."
- Be succinct. READMEs can be long, but that doesn't mean users need to read pages to understand why they should be interested in your project.
- Avoid the passive voice.
- Focus on why users would want to interact with your project, not just what your project can do.
- Use all caps to name your file. To make it easier to discover, open source projects name this file in all caps: README.md.
Content of the README template guide
The following sections provide guidance and context on how to fill out the README template.
The README template is customizable; you can reorder and remove sections or content that do not apply to your project.
About the "Project logo and badge" section
A project logo can be helpful for users to visually identify your project.
Badges highlight important information, such as status indicators, health checks, or social media accounts. Badges can also provide validating information for users that your project is current and updated. Embed relevant badges to your README to add credibility to your project. Learn more about badges and view examples.
About the "Project Name" section
The project name should be prominent in the README and easy for users to identify. A project name is usually included as an H1 heading. You may also want to consider adding the following to help identify the project:
- Project URLs
- Names of project owners
Note: Consider the stage your project is at and how much information is required in your README. Names associated with the project may be better located in a separate contact document, such as an Our Team document. View The Good Docs' Our Team template and guide.
About the "Table of contents" section
A table of contents can be useful in the case of lengthy READMEs. As the project evolves, the README may 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 about the GitHub TOC.
About the "Project description" section
The project description is the most critical part of your README. Describe what the project does and explain why a user should care about your project. Avoid describing any languages, technologies, or tools that were used in the creation of your project until after you have given a strong description on why the user should engage with the project. In some cases, you may want to specify any project limitations or when a user would not want to use the project.
Screenshots or videos may also be included in this section to help users 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 project description. 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 Good Docs Project, you can discover open source project documentation templates. This project helps you build new documents and transform existing ones into relevant and helpful documentation that serves your users. Unlike googling and searching for an assortment of document templates, The Good Docs Project provides a one-stop location for all your template needs.
About the "Who is the project for" section
Identify who your project users are and state who can use the project. Describe the problems your project can help users solve and what tasks the project can help users accomplish.
Example: This project is intended for software developers, technical writers, and project managers who want processes, templates, and guides to help create open source documentation.
About the "Project dependencies" section
List any prerequisites a user needs to interact with your project. You may want to consider including descriptions on why the prerequisites you list are required for your project to provide context and awareness for your users. Include relevant links to installation instructions or resources. Examples of project dependencies include:
- Familiarity with an application
- Software and tools
- Environments
- Authentication and authorization information
- Guides or informative documents
About the "Instructions for using project" section
Include clear instructions to help a user understand how to use your project. Instructions are procedural steps that are typically formatted in an ordered list. Start each instruction with a verb.
About the "Install {Project Name}" section
Describe in clear steps how to install or download the project to a user's device.
About the "Configure {Project Name}" section
Describe in clear steps how to configure the project.
About the "Run {Project Name}" section
Describe in clear steps how to run the project.
Note: You can include links to Getting Started documents or Quickstart Guides to support your users. View The Good Docs' Quickstart template and guide.
About the "Troubleshoot {Project Name}" section
Describe in clear steps how to troubleshoot common issues. You can use a table for troubleshooting common issues to clearly identify issues and solutions.
About the "Contributing guidelines" section
Provide clear instructions on how users can contribute to the project by linking to your contributing guidelines document or by embedding the guidelines in your README.
Note: Consider the stage your project is at. While most contributing guidelines are provided in a separate document, a smaller project may include guidelines in the README if the guidelines can be summarized in a few sentences.
About the "Additional documentation" section
Provide additional documentation for users by including links and brief descriptions. Examples of additional documentation include:
- Project website
- Twitter handles of project/project owners
- Relevant examples
- Next steps
- Features planned
- Known bugs
- Documentation files
- Sub-READMEs
- Help commands
About the "How to get help" section
Provide guidance for users seeking assistance by including links and brief descriptions. Examples of help resources include:
- Google group/mailing list
- Email addresses
- IRC, Slack, or Discord channels
- Bug trackers
- Stack Overflow
About the "Terms of use" section
Include your project license and other relevant licensing information.
Additional README resources
- Daniel Beck's README checklist
- Daniel Beck's Write the Docs "Write the Readable README" presentation
- List of README examples compiled by matiassingers
If there are other README resources you think can be linked in this guide, please open an issue to let us know!
Explore other templates from The Good Docs Project. Use our feedback form to give feedback on this template.