README file is the first source of other people’s understanding and impression of the project. Especially for open source projects, it is very important, it is like a person with a face and a company with a homepage, but many projects do not pay attention to this. The warehouse is so vast that there is no concise and clear introduction. How to let people look it patiently?
This article exists to improve the situation, to write a good README for a project. It will guide you on how to write a friendly and easy-to-read README while providing a one-click tool to generate professional README (template).
So as to solve the troubles of how to write a good README for the majority of developers. At the same time, for many readers, ease there is no clear README glimpse into the distress of the project’s thrust.
Generate README.md in one click
Earlier, when I learned about NPX related functions, I made a tool on Github Gist: Generate a good README .
If your computer has Node (version> = 5.2.0) installed, you can quickly generate a command with a command. Good README, just modify the specific content.
Obviously, the logo, title, and short description are necessary for the project.
It should be located at the top of the README and displayed in the center. In addition, you can add badges to mark and explain the project, these good-looking small icons.
Not only concise and beautiful but also clear and easy to read, you can link more information here, which will help to better show your project to others.
Goal and philosophy
For your project, write down your original intention, philosophy, and goals. A brief description of the motivation behind creating and maintaining a project should explain why the project exists.
Explain some prerequisites that users need to prepare before installation and use, such as:
You need to install or upgrade Node.js (> =
8.*, Npm version>=
5.2.0, Yarn is preferred).
In a particular ecosystem, there may be a universal installation method, such as using Yarn, NuGet, or Homebrew.
However, please consider if it is possible that the person reading the README is new and needs more guidance.
List how to use the examples and show the expected output as much as possible. It is helpful to inline minimal usage examples.
You can demonstrate while providing wiki links to more complex examples if they are too long to be reasonably included in the readme.
Feature support (optional)
You can use the form of a list to show the functions or features that the project now supports, which will help others to understand the value of the project further.
Including logo / demo screenshots, etc.
Tell people where they can go for help. It can be any combination of issue tracker, chat room, email address, etc.
Describe and show how to run tests with code examples.
If you have any ideas for future releases, it is best to list them in the README file.
Requests are welcome. For major changes, first, open an issue to discuss what you want to change. Be sure to update the tests appropriately.
Author and acknowledgments (optional)
Thanks to those who contributed to the project.
Copyright (c) 2020-present, your name.
Project Status (optional)
If you don’t have enough energy or time to complete the project, add a comment at the top of the README file that states that development has slowed down or stopped completely.
Someone may choose to fork your project, or voluntarily join as a maintainer or owner to keep your project going. You can also explicitly ask the maintainer.