在代码项目根目录里，我们会经常看见README.md。README是什么？它是项目的自我介绍，类似于你的简历，都是用来销售自己的，让公司雇佣你，让别人采纳你的项目。
在本文中，我将尝试着为介绍一下如何写README。
写README可以按照5W1H(what, why, when, how, where, who)的思路去写，主要还是使用What, Why, How, Who。
What
What 主要是以下两方面：
- 是什么？
- 能干什么？（提供了什么功能）
比如在 Kubernetes 的README中，
Kubernetes, also known as K8s, is an open source system for managing containerized applications across multiple hosts. It provides basic mechanisms for deployment, maintenance, and scaling of applications.
通过这段话，我们知道了如下信息：
- Kubernetes, also known as K8s, is an open source system for managing containerized applications across multiple hosts.（是什么）
- It provides basic mechanisms for deployment, maintenance, and scaling of applications.（能干什么？）
除了是什么和能干什么，还可能会有起源，License等
Why
Why 主要是说明动机:
- 为什么做？
- 解决了什么问题？
- 带来了哪些好处（benefits）？
比如在Hashicorp Vault 中，
A modern system requires access to a multitude of secrets: database credentials, API keys for external services, credentials for service-oriented architecture communication, etc. Understanding who is accessing what secrets is already very difficult and platform-specific. Adding on key rolling, secure storage, and detailed audit logs is almost impossible without a custom solution. This is where Vault steps in.
第一句话介绍了背景，第二句话说明在该背景之下，所面对的困难。最后一句告诉大家Vault这个工具就是解决这些问题的。
关于带来了哪些好处，这部分通常而言是和What中能干什么（功能）有重合的。
Who
Who 有如下内容：
- 谁维护该项目？
- 有哪些贡献者？
- 沟通方式。比如slack channel。
关于谁维护该项目，在开源项目中会默认是社区或者repo的拥有者维护。但是在内部项目，随着人员的流动，还是很有必要注明该项目当前是谁/哪个团队负责维护的。
有哪些贡献者，在开源项目中经常会在README中看见很多提交代码人的头像，这样可以激励大家去提交代码。
比如在Vue中Contribution部分就做了这件事情。
沟通方式和下面的部分内容有一定的重复，提供一个或者多个平台，发布信息，让大家交流，提供反馈等。
How
这部分重点关注两类人：使用者和开发者。
使用者，也就是用户。对于用户，我们需要告诉用户如下内容：
- 使用的前置条件（Prerequisite）。安装哪些依赖，需要什么credentials等等。比如我写一个docker-compose文件用来在本地运行Jenkins，那么我的前置条件就是：docker和docker-compose已经安装在本地了。
- 如何安装？个人建议：提供一个脚本实现一键安装，这样可以降低用户使用门槛。
- 如何使用？
- 如何卸载？这部分内容是绝大数项目所缺少的，本来的我只是想尝试一下，结果我安装之后就无法卸载了，这也是一件很蛋疼的事情。
- 如何提供反馈？用户在使用过程中，出现了bug，用户在哪里反馈这个bug。通常情况下，用户可以提issue，可以不写。如果不是，应当写出来。
这部分内容通常会集中在Documentation或者Getting Started这一类的标题之下。
比如在Hashicorp Vault 中，Documentation, Getting Started, and Certification Exams就是用来告诉用户如何使用。
再比如在Vue中，Documentation就是指向一些案例和文档，Issues就是告诉用户遇到问题如何创建一个issue。
开发者，可能对你项目感兴趣的人，想在你的基础上添加一些功能，或者发现了bug帮助你修复。我们需要提供给开发者Contributing Guide，包含如下内容：
- 技术栈。可以考虑使用badge来标示关键依赖。badge可以参考https://shields.io/
- Code of Conduct
- CI/CD 状态。建议使用badge。
- 如何执行测试？
- 如何执行代码风格检查?
- 如何构建（build）?
- 如何提交代码？如果涉及多分支，说明不同分支的用途。
以上的每一项不一定都需要，以上的内容也不是全部内容。通常这部分内容会出现在Development，contribution等这一类的标题之下。
比如在Hashicorp Vault 中，有一个小节Developing Vault来告诉开发者如何开发。
在Vue中，并不是将如何贡献代码写到了contribution之下，而是将其内容放到了另外一个页面，这是非常好的做法。在写README的时候，如果某个部分内容太长了就应该将其移到另外一个文件中。保持README完整，简洁，有条理是很重要的。不要尝试着增加用户（使用者/开发者）的阅读负担。