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

如何为项目编写良好 README

一键生成 README.md

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

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

顶部信息

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


LICENSE

Prettier

Arya - 在线 Markdown 编辑器

Chat On V2ex

Chat On Hacpai

Arya - 在线 Markdown 编辑器

Author nicejade

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

如何为项目编写良好 README

目标与哲学

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

先决条件

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

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

安装

1
npm i

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

用法

1
npm start

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

功能支持(可选)

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

屏幕截图(可选)

包括 logo / demo 截图等。

支持(可选)

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

测试(可选)

1
npm test

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

路线图(可选)

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

贡献(可选)

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

作者和致谢(可选)

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

执照

MIT

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

项目状态(可选)

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

于深圳.福田 @2020.01.09

原文首发于个人最新博客:如何为项目编写良好 README | 静轩之别苑

打赏

静晴轩 ~ 晚晴幽草轩
个人微信公众号晚晴幽草轩;名字取自:“天意怜幽草,人间重晚晴”。
专注互联网开发(Web 大前端、快应用、小程序),以及分享优质网站、AI 应用、效率工具、心得感悟等内容。

文章目录
  1. 1. 一键生成 README.md
  2. 2. 顶部信息
  3. 3. 目标与哲学
  4. 4. 先决条件
  5. 5. 安装
  6. 6. 用法
  7. 7. 功能支持(可选)
  8. 8. 屏幕截图(可选)
  9. 9. 支持(可选)
  10. 10. 测试(可选)
  11. 11. 路线图(可选)
  12. 12. 贡献(可选)
  13. 13. 作者和致谢(可选)
  14. 14. 执照
  15. 15. 项目状态(可选)