Markdown 工程师也不简单：如何写一个高逼格 README

最近一个项目从程序员变成了一个高级文档哥，好吧，我还称不上高级，但是我发现写文档真不是一件容易的事情，要怎么写的让人看的舒服、巴适、爽的不行，看完就想给你个赞呢？我也总结了一下写文档的一些感想，也不能说是经验，毕竟小弟还年轻，哈哈。

编写一个项目的 README 就像是写一本书的序言一样，一个好的项目不应该仅仅只有一份高质量代码，同时更应该有一份高质量的文档。而对使用者来说，一份好的文档能够节省大量的时间。

国际化

要知道比如 GitHub 这样的代码托管平台，可是有着另一个名字，全世界最大的同性交友网站（技术基不说话），你的项目可能不止中国的程序猿在使用，一个好的项目，使用者来自世界各地，那么一份中英双语的文档至关重要。

毕竟对母语的文档有更加亲和的感觉，同时阅读起来会更加顺畅。

比如，Ant Design Pro 的文档：

项目是干什么的

首先，要有一个项目名，不一定要霸气，但是一定要朗朗上口，不会读起来很拗口，而且别太长。

比如说，chalk、react、vue、commander 等等。如果自己实在不知道怎么起，搞个随机函数，试试自己的运气吧。

当然了，如果你有 LOGO 是最好的了，一张高清大图 LOGO 帅一脸，看起来就舒服有木有。

就比如说这样：

或者这样：

再接下来，一个好的项目简介，能够帮助使用者了解他能够使用这个工具干什么，能不能满足自己的需求。一般来说，我们希望从简介中，了解下面一些信息：

什么语言写的？Node、Python 还是其他什么
这个项目的用途是什么
最新版本信息
构建、测试结果等信息
Demo 演示地址或者官网

就像这样：

对于我们技术 README 一定要各种徽章砸脸上，比如标配的 travis、coverage、npm 等等，给人一种安全感，如果你自己测试构建都没过，我用着也不放心。至于这些东西大家可以去这儿看看：shield.io

同时，我们要精要的总结项目的闪光点，有哪些特性是激动人心的，别人没有的，这是吸引用户的好方法。

比如这样：

安装及快速开始

这部分内容是是文档很重要的部分，通过这些步骤，能够让使用者快速的使用。

首先，你要告诉用户怎么去获取以及初始化项目，比如下面这样：

然后你需要给一个简单的例子，让使用者快速感受到使用它的好处：

当然了，在这个地方，最好最直观的方法就是放一张 gif 的图片，吸引用户的注意力，同时给用户展示使用结果，比如这样：

API

API 是一个项目的灵魂，这是暴露给用户最直接的地方，当使用者有疑问的时候，他会第一时间去找你的 API 文档。

对于一个 API 应该表述清楚的是：

作用
入参及每个参数是否必须，数据类型是什么等等
返回值

如果你的 API 不多，那么可以放在一个文件里，但是如果你的 API 非常多，那么建议你将 API 单独放到一个文件里，这个文件留一个链接就可以。

同时，如果你的 API 有相当多个版本，那么需要准备几份 API 文档，应对不同的需求。

就比如这样：

版本变化

还有最好是能有一份 CHANGELOG 文档，对不同版本做了哪些修改，有什么特性等等，让用户知道每个版本干了什么。

就比如这样：

FAQ

当然了，如果你不想回答一些非常重复的问题，我想你需要一份 FAQ 来记录一些常见问题。

贡献

我相信很多人跟我一样，能给一些知名仓库提交 PR 是一件比较自豪的事情。

所以如果能提供一个提交 PR 的方式或者是途径，能够吸引更多的人来贡献代码，同时将贡献者，展示出来，我想会有更多人愿意贡献出自己的力量。

比如在这样的列表中也是挺有意思的：

版权

相信前不久 Facebook 的开源协议事件大家都知道，也是闹得沸沸扬扬，所以，对于开源协议等等的版权问题一定要慎重，如果你想做的不是一个玩具项目，那么关于这块一定要写清楚。

总结

最后，总结一下，对于一份好的 README 来说，这些也许够了，也许不够，但是，文档始终是因为使用者才存在的东西，所以使用者关注什么，什么才是我们文档的重点。

但是这些基础是我们应该都需要的：

名字
简介
功能
安装配置
快速教程
API 文档

这些是使用者都会去关心的点，应该在编写之前好好斟酌。

这些只是我在做一些文档工作的时候，查看了挺多的文档，综合感想，写了这么多，但是实际情况可能会大有不同，所以具体是不是要这么写，大家见仁见智啦！

文 / 小烜同学
天衣无缝的秘密是: 做技术，你快乐吗？

编 / 荧声

你可以在 Github 关注本文作者哦。

本文已由作者授权发布，版权属于创宇前端。欢迎注明出处转载本文。本文链接：https://knownsec-fed.com/2018...

想要订阅更多来自知道创宇开发一线的分享，请搜索关注我们的微信公众号：创宇前端（KnownsecFED）。欢迎留言讨论，我们会尽可能回复。

欢迎点赞、收藏、留言评论、转发分享和打赏支持我们。打赏将被完全转交给文章作者。

感谢您的阅读。