Make writing a habit together! This is my first day to participate in the “Gold Digging Day New Plan · April More text challenge”, click to see the details of the activity.

Seeing a simple, high-quality README is a great start to a development journey.

This article aims to guide you through some examples and DOS and don ‘ts on how to write a pleasurable README.

1 and 2 are README writing specifications commonly used by the author for [business project] and [open source component].

3 is a check list to see if your README is clean and of good quality.

1. Business item README specification

README for business projects is more for developers of business projects, we should focus on showing the implementation details of the project.

At this time, the purpose is to let the new developers, can quickly understand the project structure, get started with the development, verification, deployment, online process, further, for the front-end project, can sort out the page and path mapping table, convenient developers quickly familiar with the project and locate problems.

At the same time, if common systems such as monitoring, data reporting, error log system are also attached to the relevant entry, it will be even better.

## Project introduction

-Required product description-[Optional] Project LOGO/ screenshot/demo GIF-[Optional] Project background## Technical architecture

-Required. Technology selection-[Optional] Relationship between services/entity relationship and location within services## Get started

-Required. Environment dependency and installation/general function development process## Project structure

-Mandatory. File directory structure## Development process

-[Required] Development mechanism Branch management code review and merge deployment process Test process/go live process;-[optional] Can be outside the chain, link and additional supplement;## Other guidance links

-Optional: Monitoring link-[Optional] Error log link-Optional: Link to reported data## page path

-Mapping between the page and the code pathCopy the code

2. README specification for open source component project

README for open source component projects is more for component users, focusing on telling them what components do and how to quickly learn them.

Ideally, the project introduction should include a concise sentence that summarizes the core functionality of the component.

Q&A is the most direct embodiment of component user friendliness.

Add “How to join” and “Team Introduction” if you want other people to contribute to the component, or you want users to participate in the project communication.

## Project introduction

-Required product description-[Optional] Project LOGO/ screenshot/demo GIF-[Optional] Project background## Get started

-Required. Environment dependency and installation/general function development process-Optional: API document or API link## FaQs

-[Optional] Frequently asked Questions and official answers## How to join

-[Optional] How to contribute to open source projects## Team introduction

-[Optional] The role division of members, official communication channelsCopy the code

3. The final Check List

Refer to the check list of the article on the Art of README, write the README, go through the check list, and refine it further.

  • Explain the purpose of the module in one sentence
  • Necessary background information or links
  • Provide links to information sources for potentially unfamiliar terms
  • A concise runnable instance
  • Installation instructions
  • Detailed API documentation
  • 对Cognitive funnelThe implementation of the
  • The aforementioned considerations and limitations
  • Don’t rely on pictures to convey key information
  • license

Refer to the article

The art of the README

Past oliver

Say goodbye to Bad Code

2022 Code Specification Best Practices (with Web and applets Best configuration examples)

【 Front-end Exploration 】 Say goodbye to bad code! Encapsulate network requests in the chain of responsibility pattern

【 Front-end Exploration 】 Say goodbye to bad code # 2! Encapsulate sharing components with policy patterns

The code of life

[Thinking on three years of front-end development] How to read requirements effectively?

Front end step pit must see guide

[Front-end exploration] Best practices for image loading optimization

[Front-end exploration] Exploration of mobile terminal H5 to generate screenshot posters

[Front-end Exploration] H5 to obtain user positioning? This one is enough

【 Front-end exploration 】 The exploration of wechat small program jump — Why does open label exist?

VConsole fancy usage