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）。欢迎留言讨论，咱们会尽量回复。

欢迎点赞、收藏、留言评论、转发分享和打赏支持咱们。打赏将被彻底转交给文章做者。

感谢您的阅读。