How to write a generic README specification

background

When we usually develop projects, we usually upload the code to the code hosting platform to facilitate management and maintenance. At present, the most used hosting platform is Github, and there are some well-known code hosting platforms at home and abroad, such as Gitlab, BitBucket, Code Cloud and Code Market.

However, the most troublesome problem we often encounter under the cooperative development of multiple people is that when other developers hand over a project to us, they only briefly describe the existing functions of the project. I found that even the most basic projects were not explained to us. At that time, there were 10,000 horses galloping past, and I could only check the scripts of package.json, and I understood it myself.

So the question is, when we hand over a project, how can we ensure that the project can be quickly and completely delivered to our friends, so that we can live a carefree life? The answer is that we just need to throw him a standard specification README.

 

What does a canonical README need

Let's take a look at what a simple README specification has through a screenshot:

So let's discuss together, what should a complete README specification contain?

1. Project Description

2. How to run

3. Business introduction

4. Project Notes

What does each do?

• project description

  We need to explain our project name, brief description of project functions, code warehouse address, and the first person in charge of the project. Whoever hands over the project to us is the first person in charge of the project.

• how to run

  1. Development environment configuration . Generally, it is some running environment configuration we need.
  2. Develop & publish commands . How do we start local development through commands, and build and publish.
  3. proxy configuration. If our project needs to use some proxy tools when developing locally, such as fiddler or whistle, we need to list the configuration items of the proxy. It is best to directly export a proxy configuration file and put it under the project
  4. release. If we use some publishing platforms, it is best to paste the project's release module and release order to reduce the time cost of our release.
  5. Error alerting and monitoring . I believe that we usually deploy error alarm and monitoring log services for online projects, so that we can troubleshoot existing network problems in a timely manner. Here we can add some monitoring attribute IDs of the project.
  6. Interface API . Here we need to paste the address and description of the background interface pulled from the project, as well as our interface leader. When the background service is abnormal, we can directly contact the background students.
  7. data reporting . We have added some data reports to the usual projects, which are used by product students to count business data. Here we'd better explain what data are reported. If there is a problem in the report, and the product girl comes over, we will not be confused.

• Business introduction

  For the front end, our project may have more than one page, then we need to give the following information:

  1. The business entry address and channel link are the entry page of our entire project, or the more important page address. On the general entry page, we may run it in multiple channels, so we need to list all the channel links

• 1. Each page and description List all page information in our project, such as the following:

     page directory	page description	page link	Parameter Description
     index	front page	https://xxx.com	without

• Project Notes The project needs to tell other developers some key information, such as our page packaging and construction, what problems need to be paid attention to, etc. Although this information is not necessary, it can help other developers reduce the risk cost of development.

 

finally

The above is some information and content that we need for a standard README. The bolded content is some necessary information in the README. You can also expand some standard information according to the actual development scenario of your own project on this basis.