開源日報 每天推薦一個 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/