The README file has a long tradition in software projects. Its purpose is to serve as the entry point for everything you might want to know about the project. You may not necessarily include all information, but you should at least link to it form the README. Even if you are just dumping your code onto GitHub and don't plan to support the project for others, it should include a README file.
Traditionally README files are plain text. Most projects typically use a text-based markup which renders nicely in GitHub. Markdown is the simplest and most readable when viewed as plain text. AsciiDoc and reStructuredText are more powerful and have features such as admonitions and generated table of contents.
The following sections will list and describe the major top-level sections you might find in a README file. You don't need to include every possible section in your read me file.
- Project Name
- Shields
- Logo/Icon/Banner
- Download Badge
- Short Description
- Table Of Contents Section
- Screen Shots
- Feature List
- Requirements
- Installation
- Configuration
- Usage/Quick Start
- Documentation
- Examples
- FAQ
- Troubleshooting
- Non-Goals
- Changes
- Contributing
- Contributors/Credits
- Security Disclosure
- Donations
- Author(s)
- Support/Help
- Community/Communication
- Commercial Support
- Sponsors
- Projects Using X
- Disclaimer
- Related Projects
- Alternatives
- About
- License
| ❗ | Every project, no matter how trivial, should include this section. |
|---|
Choosing a project name can actually be quite difficult. Here are a few considerations to make.
This can be a good idea if you plan to have multiple implementations of your project using different languages or if there is already an existing project or common name which you are implementing in another language.
Avoid using a generic word or a common combination of words for your project. Selecting a somewhat unique name will make it easier for someone to search for your project.
Shields are a great way to display important information about your project in a small amount of space. Most shields you see on GitHub are from Shields IO. Shields are commonly displayed directly under the project name heading, sometimes above it.
A continuous integration status shield displays the build health of the project from a CI system like Travis CI. The CI system will usually offer you a link you can copy-paste in your favorite format (HTML, Markdown, AsciiDoc, etc...). The color of the shield will correspond to the build health. Green means good, red means failure.
By putting the license in a shield you make it easy for visitors to quickly determine if this project is compatible with theirs. This shield should link to the license itself, either the official website or your embedded LICENSE file. It's also common to link to Software Licenses in Plain English.
Let readers know the latest stable release by including this badge. If the project is still young and hasn't had a stable release yet, it's common to make the badge orange or red to indicate that.
| 💡 | Use a tasteful size for your graphic, don't make it so large that you have to scroll far to get to useful information. |
|---|
| 💡 | Remember to include alt-text on your images for accessibiliy. |
|---|
A graphic is commonly placed in one of the following locations:
- Above the project name header
- Example: Actor Messaging platform
- Example: osquery
- Right of the project name header and description
- Example: Awesome README
- Example: bluebird
- Left of the short description
- Example: D3
- In-line with the project name
- Example: RxSwift
- Example: BitBar
- Example: FlatBuffers
- Banner above the header
If your project is available for distribution through an app store or package manager they often provide badge assets to visually call out that your project is included.
See App Store Download Badge for details on its use.
See Google Play Badge Page for details on its use.
| ❗ | Every project, no matter how trivial, should include this. |
|---|
| 💡 | If you are using GitHub then you should set the project description. The description is meta-data that appears in search results. You can re-use your opening sentence for this. |
|---|
Describe the most relevant high-level information in one short paragraph. Try to get the most important information in the first two sentences. The goal is to save the reader time by explaining the project's purpose.
Example Opening Sentences
-
Alamofire is an HTTP networking library written in Swift.
-
The Apache HTTP Server is a powerful and flexible HTTP/1.1 compliant web server.
-
D3 (or D3.js) is a JavaScript library for visualizing data using web standards.
-
libgit2 is a portable, pure C implementation of the Git core methods provided as a re-entrant linkable library with a solid API, allowing you to write native speed custom Git applications in any language with bindings.
| 💡 | This is optional, but if your README is long, you should include a TOC. |
|---|
Sometimes called "Contents". If your README is long enough you might consider including a table of contents. AsciiDoc and reStructuredText formats support automatic generation of the table of contents.
- Example: Eureka
If you include screenshots, set the width or height property to ensure they are not oversized. This is especially important when your screenshots are from a high-dpi device but the README is being read on a low dpi-device.
Typically called just "Features". A feature list can be a set of bullet points. If you want to include commentary on each feature you can use sections instead. If your feature list is very long or includes a lot of detail, consider putting it in its own file in the Docs Directory and linking to it from this section.
- Example: Git Book
- Example: SQLite.swift
List the requirements for your project. If you require a specific version of something, be sure to include that information.
Ideally you will distribute your package as part of the appropriate repository. For example, if this is a Perl project you might use CPAN, a Go library, use Go's manager, Node use npm etc...
- Example: SwiftLint
- Example: SQLite.swift
- Example: Dokku
⛔️ ToDo: This section is a stub
If your project is highly configurable consider making this its own document in the <> and linking to it from this section.
- Example: SwiftLint
⛔️ ToDo: This section is a stub
Sometimes called "Guide" or "Tutorial" or "Getting Started".
- Example: SwiftLint
- Example: SQLite.swift
- Example: Git Book
- Example: Swift
- Example: Electron
If you hope to get people to use your project you will need to take documentation seriously. Some projects are small enough that they can fit all their documentation in the README itself (example). If it gets too long, then move it to the Docs Directory and refer to it from this section.
⛔️ ToDo: This section is a stub
⛔️ ToDo: This section is a stub
- Example: Eureka
⛔️ ToDo: This section is a stub
This section is often included in projects whose documentation fits within the README.
- Example: Homebrew
This section is fairly uncommon, though it should be used more. It can be very helpful to list things your project isn't meant for. This can help limit the scope of your project and set expectations. Non-goals can also help keep outside contributions and questions more focused on the project goals.
Sometimes called "Version History". Typically you would refer to and link the CHANGELOG file or releases section of your project site.
Typically this section just refers you to the CONTRIBUTING file. Even if it's already mentioned in the CONTRIBUTING file, it might be a good idea to state whether contributions are welcome.
- Example: Swift
- Example: List of Free Learning Resources
- Example: Xi Editor
May be called "Maintainers". List of people who contributed to the project. Yes, sites like GitHub already have a feature that let you see a list of contributors, and you can probably figure it out through the repo history too, but it might still be valuable to have this in the README because it lets you curate the list, order it based on influence or number of contributions, or take out old contributors who are no longer involved.
- Example: Homebrew - Who Are You?
- Example: traefik - Maintainers
- Example: traefik - Credits
⛔️ ToDo: This section is a stub
- Example: Docker
- Example: bugcrowd/disclosure-policy
- Example: Homebrew
⛔️ ToDo: This section is a stub
- Example (Bountysource): XVim
- Example (PayPal): AdminLTE
- Example: MacDown - Tipping
- Resource: Create a PayPal Payment Button
- Example: Homebrew
Different from the Contributors section in that this lists the original author(s) of the project. You may want to also include links to your blog and Twitter handle.
- Example: Eureka
- Example: SQLite.swift
- Example: Xi Editor
⛔️ ToDo: This section is a stub
See next section: Community/Communication.
- Example: Git Book
Depending on what type of community groups exist for your project, you might point users to: stackoverflow, irc, mailing lists, slack, wiki, forums etc...
- Example: Electron
- Example: MacDown - Discussion
- Example: SQLite.swift
Often commercial support is simply mentioned in a sentence in the Community/Communication section, referring to the maintainer's email for details on commercial support.
- Example: Java Native Access (JNA)
- Example: traefik
Sufficiently large projects may receive funding and list their sponsors here. You can also provide details about how to become a sponsor. Sometimes this is name "Backers".
If your project is being used by other projects or well known entities you can list them here.
- Example: Java Native Access (JNA)
Most software licenses will typically include a disclaimer so this section isn't necessary most of the time. If people might jump to certain conclusions about your project it might be a good idea to call it out in its own section. Another reason to add a disclaimer would be to distance your project from your employer, if it might be easy to draw conclusions about their involvement.
- Example: Malcom - Malware Communication Analyzer
- Example: Investing Returns on the S&P500
- Example: Xi Editor
If your project may have plug-ins or extensions it may be a good idea to list some of them here.
- Example: SQLite.swift
Projects rarely include this section, but it could be helpful to the reader. You don't have to exhaustively list every similar library, but mentioning a few common ones can be useful.
- Example: SQLite.swift
⛔️ ToDo: This section is a stub
- Example: SwiftLint
| ❗ | You should always include a license with your project. |
|---|
Although you probably already have a shield with the license, it doesn't hurt to explicitly call it out again here. This is typically the last section of the README. If the license is short you can include the contents, otherwise link to the LICENSE file. Even if it's obvious it does help to actually mention the name of the license instead of just including its contents. For example: say it's "MIT", "2-clause BSD" etc...
- Example: SwiftLint
Many projects now use FOSSA to track license compliance and attribution.
- Example: NervJS license section