今日推荐开源项目：《每年一读 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.
- 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.
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.
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://opensourcedaily.org/2579/
加入我们：https://opensourcedaily.org/about/join/
关注我们：https://opensourcedaily.org/about/love/