如何为项目编写良好 README

README,它是别人对项目了解、印象的第一来源;尤其是针对开源项目,相当之重要:好比颜值之于一个人,主页之于一个公司;但很多项目并未重视这一点;各种仓库,浩如烟海,没有简洁、明晰的介绍,教人如何耐心去看?本篇文章的存在,即是为了改善这种情况。它将指导您如何写出一篇友好、易读的 README ,同时提供一键生成专业 README(模版)的工具,从而为广大开发者,解决如何书写良好 README 之烦忧;同时为诸多阅读者,缓解没有清晰 README 一窥项目主旨的苦恼。

一键生成 README.md

先前在了解 npx 相关功能时候,有特地在 Github Gist 上做了一个工具:Generate a good README,如果您的电脑已经安装 Node(version >= 5.2.0),那么即可通过一条命令,快速生成一个良好 README,只需对其中具体内容做下修改即可。

# 默认英文 README  
npx https://gist.github.com/nicejade/406f154e882a836de1b2e12d02b84aab  
  
# 生成中文 README  
npx https://gist.github.com/nicejade/406f154e882a836de1b2e12d02b84aab zh  

顶部信息

显而易见,Logo标题简短描述,对于项目是必要的;它应该位于 README 顶部,且居中显示;除此之外,还可以添加徽章(Badge),对项目进行标记和说明,这些好看的小图标,不仅简洁美观,而且清晰易读,您可以在这里链接更多信息,这有助于更好向他人展示自己的项目;正在维护的 nicejade/markdown-online-editor 项目,就添加有以下徽章:

如果您习惯使用中文,但项目又是国际化的,那不妨考虑以英文来书写 README,这似乎更有逼格(毕竟代码也是英文);但为人性化考量,也应该提供其他语言版本 README,可以在徽章之下,添加网页跳转链接。

目标与哲学

为您设计的项目,写下初衷、理念和目标。对创建和维护项目背后的动机,作简短的阐述,这应该可以解释为什么该项目存在。

先决条件

说明用户在安装和使用前,需要准备的一些先决条件,譬如:

您需要安装或升级 Node.js(> = 8。*,Npm 版本 >= 5.2.0Yarn 作为首选)。

安装

npm i  

在特定的生态系统中,可能存在一种通用的安装方式,例如使用Yarn,NuGet或Homebrew。但是,请考虑是否有可能正在阅读README的人是新手,并且需要更多指导。

用法

npm start  

列举如何使用示例,并尽可能显示预期的输出。内联您可以演示的最小用法示例很有帮助,同时提供指向更复杂示例的 Wiki 链接(如果它们太长而无法合理地包含在自述文件中)。

功能支持(可选)

您可以用列表的形式,展示项目现在已经支持的功能或特性,这有助于他人对项目存在的价值,做更深一步了解。

屏幕截图(可选)

包括 logo / demo 截图等。

支持(可选)

告诉人们他们可以去哪里寻求帮助。它可以是 issue 跟踪器,聊天室,电子邮件地址等的任意组合。

测试(可选)

npm test  

用代码示例描述并展示如何运行测试。

路线图(可选)

如果您对将来的发行版有任何想法,最好在 README 文件中列出它们。

贡献(可选)

欢迎提出请求。对于重大更改,请先打开一个 issue,以讨论您要更改的内容。请确保适当更新测试。

作者和致谢(可选)

向那些为该项目做出贡献的人表示感谢。

执照

MIT

版权所有 (c) 2020-至今,您的名字

项目状态(可选)

如果您没有足够的精力或时间来完成项目,请在 README 文件的顶部添加注释,指出开发速度已减慢或完全停止。可能有人会选择 fork 您的项目,或者,以维护者或所有者的身份自愿加入,从而使您的项目继续进行下去。您也可以明确要求维护者。

于深圳.福田 @2020.01.09