README is one of the first things we look at when we approach a new project, both internally and in the open source community. A good README can get you up to speed on a project, while a bad one can crash you.
README is like an introduction book for developers to read. In order to write this book effectively, for others or for ourselves, we need to learn some techniques for writing highly readable README.
What is the README
A README (as the name suggests — “README”) is the first file you need to read when starting a new project. It is a collection of useful information about the project as well as a manual.
An egg in the README
The benefits of a good README
For people working on your project, a good REAME lets others quickly understand what our code contains, what’s important, how to use it, the technology stack, any problems, etc. There is no doubt that this can greatly reduce communication costs. Write a complete and readable README if you don’t want to answer a lot of questions from newbies.
For us, the README not only helps you find a sense of familiarity after a long time away from the project, it also helps us summarize and plan. We can record the source of inspiration for solving the problem (such as stackOverflow links), and we can also add completed features and upcoming features and optimizations. In this way, it’s like a diary or blueprint for a project.
What language to use
For open source projects, I recommend using English. After all, we should have an international heart. If it is an in-house project, Chinese is more “readable”.
What the README should include
The first thing that should be included at least is:
- The Title (the Title)
- Introduction (the Introduction)
- Technology stack (Technologies)
- Launch or Setup
If considered more fully, it also includes:
- Table of Contents
- Features:
- Code Examples
- Project Status
- Source (Sources)
- External Links
- (Contact)
- Other information
- .
Of course, as far as content specification is concerned, it’s a good practice to be as good as a README should be.
The title (the title)
A title should clearly express what the project is about. Typically, it will be the project name.
Introduction (the introduction)
The introduction should be short and concise, with 2 or 3 sentences explaining the purpose of the project and the problems it will solve.
Technology stack (Technologies)
This is one of the most important things programmers care about. They are the foundation of the project, complete and correct in order to build the whole project, rather than numerous errors from the start. Therefore, we should write down the language, dependencies, and corresponding versions of the project. Such as:
- Java 8
- Spring Boot 2.x
- Easyexcel 1.1.0
Launch or Setup
How it works is also of great concern to developers. We can’t just write down a single start command, such as NPM run start. In general, we also need to tell the consumer how to install dependencies, modify configurations, and even initialize the database. The more detailed you are, the less people will tease you.
Table of Contents
In the case of longer and more content, the table of contents provides a shortcut to the content of each part, rather than an endless scroll. We can create a simple directory using the convenient syntax provided by Markdown.
Features:
By reading this section, people will quickly understand the features and features supported by the project. In addition, we should also include the TODO List so that we can plan the project and others can know its future direction.
Code Examples
This is important for some tool – or library-dependent projects. Because usually people prefer to just copy and paste to test what they want.
Project Status
Is the project under development or completed, has maintenance been stopped or migrated to a new project? It’s worth telling the reader.
Source (Sources)
In the process of developing a feature or fixing a bug, we sometimes consult documentation, tutorials, or technical forums to find a ready-made solution (stackOverflow, nuggets, etc.). Write down a description and a link to any of them that you consider valuable to yourself or others. I think it might help you or someone else at some point in the future.
External Links
For internal projects, there may be project management platform addresses (such as TAPD), interface document addresses; There may also be full documentation, tutorials, blogs, etc for open source projects.
(Contact)
It is mainly to record the contact information of the author or the development team.
conclusion
The above are just personal opinions and suggestions. As long as it is suitable for your own project, highly readable and achieves the purpose of reducing communication costs, it is a good README.
Inspiration: www.flynerd.pl/2018/06/jak…