写好项目文档有多重要？关于我被百大 UP 主选中又放鸽子这档事

论写好项目文档的重要性和方法。

还记得前段时间火遍全网的合成大西瓜游戏么？

其实当我刚刚听说这个游戏的时候，属于村里刚刚通网，当时这个游戏都已经在网上传遍了，而且也有同学扒光了源码，并公开到了 GitHub 平台。

正好当时是午休，我就看了下这个游戏的源码，发现做一些简单的修改难度并不大。正好有同学在网上求修改的方法，索性我就认认真真地出了一个『魔改大西瓜教程』，并且也在 GitHub 上建了一个项目。

结果没想到，很快这个项目就后来居上，霸占榜首！相关教程也在网上疯传，总阅读量也有几十万！

值得一提的是，有一位 B 站的 百大 UP 主（粉丝 300w+）看到了我的项目后，主动联系我能否和他合作，为他的视频提供技术支持。

作为一名 1024 线小 up，有机会和大佬合作，我是非常激动的，当晚我们就电话联系，并且第二天帮他完成了需要的作品。

从那天之后，我就一直期待这位百大 up 发布这个视频，小小地提携自己一笔。

结果，这一等，一直等到了游戏过气，也没看到视频发出来。

特么的被鸽了！

不过我也没觉得生气，毕竟有圈层差距，在几百万粉的大佬眼里，这叫事儿么？

但还是感谢他，让我明白了一个编程道理，那就是 写好项目文档的重要性。

我当时问他，为什么网上这么多魔改大西瓜游戏的教程，我也不是最早发的，为什么偏偏选中了我呢？

他说：“我看了很多的项目，只有你的项目文档上的链接，是可以直接访问的。”

原来如此，是 “第一眼” 的作用！

现在网上的开源项目和产品太多了，如果想让更多用户使用你的项目，那一定要在 入口处 做足功夫。好的官网是公司产品的门面，同理，好的项目文档也是一个项目的牌面。所以，在开发项目的过程中，要持续写文档。

那如何为项目提供一份优质的文档呢？

如何写好文档

什么样的文档算得上优质呢？我总结了下面几点，大家可以从这些角度来优化项目文档。

直观通俗

如果是对外的项目文档，建议在文档的开头用最通俗的方式来让用户理解你这个项目是做什么的，而不是一上来就用些过于专业的术语。尽量让文档内容更直观，能让用户一眼 get 到项目的价值是最好的。

比如可以在项目开头加入一些统计小徽标、列举一些项目亮点图片等，还可以用一些可视化图表来代替繁杂的数据表格，帮助用户更快地理解项目。

阿里 Ant Design 的项目文档就很棒，大标题下用一句话介绍了项目是什么，然后用大量小徽标补充了项目的信息，并且放上了几张美观的组件截图。大家可以参考一下。

可体验易上手

除了内容要直观通俗外，如果能在文档中直接提供一个项目的在线体验地址，会给项目大大加分！

毕竟有很多同学相对于看文档，更喜欢自己动手体验。

除了体验链接外，如果是可运行的项目，一定要提供快速运行项目的方法，比如怎么搭建环境、怎么启动项目、设置哪些参数等。可以再提供一个小 Demo，帮助用户快速使用和学习项目。

对于后端项目，最好能够提供一些在线的数据源，不需要用户自己在本地搭建数据库和造数据。

这一点，Ant Design 的文档做的依然很好，提供了两种安装方式和简单的组件用法：

如果是开源项目，可以在文档中补充参与项目贡献的方式，吸引更多朋友为你的项目做贡献。

值得一提的是，现在很多云平台都支持用户一键部署项目，在文档中补充这个功能，能让用户更方便地运行你的项目，无需自己在本地搭建环境。

比如当时我给魔改大西瓜项目文档中添加了腾讯云一键部署按钮，可以直接上线魔改网站！

简洁清晰

一定要好好梳理下内容的顺序，尽量化繁为简，还要划分板块，让整个文档更加结构化，清晰又有条理。

如果项目文档内容较多，在文档开头，还要有明确的目录或菜单引导。

排版工整

想要提高代码的可读性，就要对其进行格式化。同理，写文档也讲究排版和格式，统一的排版和规范的格式能够提高文档的可读性，给用户良好的体验。

网上有一份开源的『中文文案排版指北』，统一了中文文案、排版的相关用法，帮助你写出优雅的文档，降低团队成员之间的沟通成本，增强网站气质。

比如中英文之间要添加空格、数字与单位之间需要增加空格等，文档地址见文末。

答疑

如果很多用户都对项目有相似的疑问，不妨在文档中补充答疑（FAQ 经常被问的问题），整理些常见的问题供用户自己参考。可以降低团队维护项目的成本，并且也让用户明白，这个项目的负责人非常贴心，值得信赖！

我在维护魔改大西瓜项目时，基本每天都有数百个问题，如果不采用这种方式，挨个回答问题，一天可能都回答不完！

易搜索

文档内容较多时，如果提供全文搜索功能，可以帮助读者更快找到自己的感兴趣内容。

现在有很多的文档站点生成工具，只要将写好的文档放到工具目录下，就能自动给你生成一个支持搜索的网站，还可以发布到服务器上供其他人公开访问！

常用的文档站点生成工具有：Docsify、VuePress、Docusaurus、Dumi 等。

用法很简单，可以参考这篇文章：实战 | docsify+云开发，高效创造你的文档网站

界面美观

文档的内容很重要，但也要保证文档页面的美观，否则也会影响用户的阅读体验和效率。

比如下面两种风格的文档，我会更倾向于后者的界面风格。

经典风格：

清新风格：

通常也不需要我们自己来设计和开发文档的界面，大部分平台都提供了默认样式。也可以用上面提到的文档站点生成工具，选用工具提供的主题，或者自定义文档界面。

最后，通过这件事，我还明白了一点：成功的路上没有捷径，还是要靠自己啊！

优雅排版文档：https://www.code-nav.cn/rd/?rid=28ee4e3e607167fa0ecab6b722c458d7