You can think of a README file as a manual for your project. READMEs are text files containing an introduction, summary, and all necessary pieces of information anyone needs to know about the project, such as what the project is all about or what steps a user needs to take to run it.
READMEs can be written in any text file format, and the all-caps naming is also just a convention that isn't absolute. You may encounter README files looking like this: readme.txt, Readme.md, or even just README without any file extension. The most common format on GitHub projects is to use a Markdown file named README.md. The Markdown format allows you to add simple formattings, such as headings, bolding, emphasis, lists, and links.
Why Have a Good README
So you've built a great project and put it on GitHub. Since you wrote it, you know exactly what the project is all about and what it contains. Your friend wants to contribute to your project, but they live far away in a different timezone than you. To avoid going back and forth to explain every bit of the project, it would be great to have a file that contains a summary of the project, as well as instructions on how to start working on the project. Such a file would help your friend to get started.
Info: After reading your README.md file, a newcomer should have a good idea of how to use your project
In short, having a good README.md makes your project more approachable for other people and is overall a great advertisement for you and your project. It is a rich manual that makes your project stand out in the eyes of other people. If your project has a quality README.md, it'll help others to understand the fundamentals and the functionality of our project quicker and make them aware of features that they might have otherwise failed to notice.
How to Write a Good README
A good README.md file describes all the necessary aspects of a project, such as its version, which technologies are used, how to run it, what the purpose of the project is, what future updates are planned, etc.
To accomplish this, your README.md file should always include at least the following elements:
Introduction
- Summary of the project,
- What the project is all about
Technologies
- Which technology and versions are used
Project setup
- Hardware requirements
- Software requirements
- The minimum requirements to run the project
- How to start the project on your own machine
How to Write an Excellent README
To make your README.md file even better, consider also using additional elements, such as:
Table of contents
A TOC gives a quick overview of the project's README.md file using links to the headings. A TOC will look something like the one below. It usually allows readers to click on the headings and be taken to the corresponding content.
## Table of contents:
- Introduction
- Technologies
- Project setup
- Illustrations
In order to create functioning hyperlinks inside of your Markdown document, you need to use a bit of HTML code and add an id element to the headings you want to link to, for example:
## Table of contents:
- [Introduction](#intro)
<h3 id="intro">Introduction</h3>
While a clickable table of contents is preferred, just adding one for overview at the top of your README.md file is already very helpful.
Visual Aids
Adding some screenshots of your project in action, or even GIFs that show the functionality, goes a long way. Depending on the project type, illustrations or graphics related to the project could be more appropriate. In general, adding visual aids will make your project's README.md file more accessible and easier to read for most viewers.
Project Information
It can be helpful to list features, TODOs, etc., which can also help to get a quick high-level overview of the current state of the project.
Project Status
Clarifying the status of the project can be helpful, especially if the project is still in development. Also, if there's a chance that a new feature might be added soon, it's a good thing to have that information noted in your README.md file.
Sources/Inspiration/References
What inspired you to do the project? Which other sites and projects helped you build it? Was there any tutorial you watched or blog post you read that helped you build the project's functionality? Adding your resources to your README.md file is important. Share the love!
Contribution Instructions
Do you want other people to contribute to your project? It's important to clarify whether or not you want that and maybe make it easier for newcomers to see where they could start out. Often, especially in larger projects, this information is separated into its own file, aptly named CONTRIBUTING.md, and should contain detailed instructions on how to get started contributing. It is extremely helpful both for yourself as well as for others when you clarify what contributions you welcome and how they should be presented to you.
Other Information
There might be some specific information that is relevant just for your project and your individual information. Feel free to add whatever you think is informative and relevant.
There are multiple great resources on the web that you can use to improve your skills in writing README.md files. For example, check out the Make a Readme site to learn more about how, when, and where to use a README.md file, as well as more detailed guidelines on how to author quality project documentation.
Summary: Python Documentation and README
- Python documentation makes collaboration much easier
- README text files are typically the starting point for any new person arriving at your project
Parts of a Good README
- Introduction
- Technologies
- Project Setup
Parts of an Excellent README
- Table of Contents
- Visual Aids
- Project Information
- Project Status
- Sources/Inspiration
- Contribution Instructions