今日推荐英文原文：《How To Write a Readable README》
今日推荐英文原文：《How To Write a Readable README》作者：Jackson Z.
How To Write a Readable README
Stop confusing developers with READMEsA 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 ObjectiveI 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.”)
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:
Step 4. Clarify the Workflow (Optional, Only if the Project Accepts Contributors)The directory/project structure:
credit: example directory structure from algorithm-visualizer
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 AutomagicallyThe 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.