开源日报 每天推荐一个 GitHub 优质开源项目和一篇精选英文科技或编程文章原文，坚持阅读《开源日报》，保持每日学习的好习惯。
今日推荐开源项目：《每年一读 Annual-Reading-List》
今日推荐英文原文：《How To Write a Readable README》
今日推荐开源项目：《每年一读 Annual-Reading-List》传送门：GitHub链接
推荐理由：这个项目是作者计划每年都要读一遍的书籍列表，今年快结束了他也准备读完了。读书，可以说是用自己去理解他人思想的一种方式，对于那些传授知识的书来说，我们用自己的知识去理解，就能够获得书中的技能；相对应的，对于那些传授一种思想的书来说，我们自然是用思想去理解，这样的书随着时间的不断经过，用于理解的思想变得不同，自然会有不同的收获，这就是为什么有些书可以反复阅读的原因。
今日推荐英文原文：《How To Write a Readable README》作者：Jackson Z.
原文链接：https://medium.com/better-programming/how-to-write-a-readable-readme-590ae6124f69
推荐理由：欲看项目先读 README

How To Write a Readable README

Stop confusing developers with READMEs

A README is a project’s first impression for developers.

A well-written README can bring traction and support to the project, but the quality of a README, compared to code, is less emphasized. As a result, developers usually put the least effort into their README.

A README should achieve four goals with as few words as possible:
  • State the objective: State the problem that the project is trying to solve.
  • Define the audience: Define who can/should the project.
  • Demo usage: Demonstrate how to start using the project.
  • Clarify workflow (optional): Clarify how to collaborate and contribute.

Step 1. State the Objective

I suggest using one sentence of the following form:
  • my awesome project is a utility/tool/framework/etc. to help my target audience do some task.
Here are a few examples from successful projects:
  • PyTorch: An open-source machine learning framework that accelerates the path from research prototyping to production deployment. (If converted to our form, it will be: “PyTorch is a machine learning framework to help (everyone) accelerate the path from research prototyping to production deployment.”)
  • React: React is a JavaScript library for building user interfaces. (React’s objective statement is almost the same as our format except their audience is everyone).

Step 2. Define the Audience

  • Define the group of users who can use it: operating system, programming language, and framework limitations.
  • Define the group of users that can/can’t benefit from the project.
Here is an example from project Moby:

credit: example target audience from Moby

Step 3. Demo Usage

  • Give users intuition about how the project works.
  • Help users get started using the project.
To achieve both, I prefer to use examples (code that works) close to real-world use cases with only the basics (leave out the fancy configurations).

The users can understand the project from the example code and they can copy-paste the code to get started using the project.

Here is an example from TensorFlow:

credit: tensorflow.com

Step 4. Clarify the Workflow (Optional, Only if the Project Accepts Contributors)

The directory/project structure:

credit: example directory structure from algorithm-visualizer

Developer setup:

credit: example developer setup from algorithm-visualizer

Best practices: Define the standard for the quality of work.

credit: example best practices from scikit-learn

Submission process: Define the process of submitting code/review/documentation.

credit: example submission process from scikit-learn

Bonus: A Tool I Built to Improve README Readability Automagically

The README is code, so it deserves linter and continuous integration too.

The readable-readme project（https://github.com/tianhaoz95/readable-readme） is a continuous integration tool based on GitHub Actions to control the readability/quality of READMEs.

When added to the workflow, readable-readme will generate a quality report for all the README files upon push/pull requests.

credit: example usage from readable-readme

This is what the generated report looks like:

credit: readme quality report from readable-readme

Note: The readable-readme project is at a super early stage. All kinds of contributions are welcome. Let’s make READMEs great again!

Opinions are my own and not the views of my employer.
下载开源日报APP：https://openingsource.org/2579/
加入我们：https://openingsource.org/about/join/
关注我们：https://openingsource.org/about/love/