11 KiB
如何为你的开源项目编写实用的文档
一份优质的文档可以让很多用户对你的项目路人转粉。
好的代码很多时候并不代表一切。或许你能用最精巧的代码解决了世界上最迫切需要解决的问题，但如果你作为一个开源开发者，没能用准确的语言将你的作品公之于世，你的代码也只能成为沧海遗珠。因此，技术写作和文档编写是很重要的技能。
一般来说，项目中的文档是最受人关注的部分，很多用户会通过文档来决定自己是否应该对某个项目开始学习或研究。所以，我们不能忽视技术写作和文档编写的工作，尤其要重点关注其中的“入门”部分，这会对你项目的发展起到关键性的作用。
对于很多人来说，写作是一件令人厌烦甚至恐惧的事情。我们这些工程师出身的人，更多学习的是“写代码”而不是学习“为代码写文档”。不少人会把英语作为自己的第二语言或者第三语言，他们可能会对英语写作感到不自信甚至害怕（我的母语是汉语，英语是作为我的第二语言学习的，所以我也能感受到这种痛苦）。
但如果你希望自己的项目能在全球范围内产生一定的影响力，英语就是你必须使用的语言，这是一个无法避免的现实。但不必害怕，我在写这篇文章的时候就考虑到了这些可能带来的挑战，并给出了我的一些建议。
五条有用的写作建议
这五条建议你马上就可以用起来，尽管看起来似乎有些浅显，但在技术写作时却经常被忽视。
- 使用主动语态：感受一下主动语态下的“你可以这样更改配置（You can change these configurations by...）”和被动语态下的“配置可以这样更改（These configurations can be changed by…）”有什么不同之处。
- 使用简洁明了的句子：可以借助 Hemingway App 或者 Grammarly 这样的工具，尽管它们并不开源。
- 保持条理性：你可以在文档中通过写标题、划重点、引链接等方式，把各类信息划分为不同的部分，避免将所有内容都杂糅在一大段冗长的文字当中。
- 提高可读性：除了单纯的文字之外，运用图表也是从多种角度表达的手段之一。
- 注意拼写和语法：必须记得检查文档中是否有拼写错误或者语法错误。
只要在文档的写作和编辑过程中应用到这些技巧，你就能够和读者建立起沟通和信任。
- 高效沟通：对于工程师们来说，阅读长篇大论的冗长文字，还不如去看小说。在阅读技术文档时，他们总是希望能够从中快速准确地获取到有用的信息。因此，技术文档的最佳风格应该是精简而有效的，不过这并不代表文档中不能出现类似幽默、emoji 甚至段子这些东西，这些元素可以当你的文档更有个性、更使人印象深刻。当然，具体的实现方式就因人而异了
- 建立信任：你需要取得文档读者们的信任，这在一个项目的前期尤为重要。读者对你的信任除了来源于你代码的质量，还跟你文档编写的质量有关。所以你不仅要打磨代码，还要润色好相关的文档，这也是上面第 5 点建议拼写和语法检查的原因。
从编写“入门”文档开始
现在，最需要花费功夫的应该就是“入门”部分了，这是一篇技术文档最重要的部分，二八定律在这里得到了充分体现：访问一个项目的大部分流量都会落在项目文档上，而访问项目文档的大部分流量则会落在文档的“入门”部分中。因此，如果文档的“入门”部分写得足够好，项目就会吸引到很多用户，反之，用户会对你的项目敬而远之。
那么如何写好“入门”部分呢？我建议按照以下三步走：
- 任务化：入门指南应该以任务为导向。这里的任务指的是对于开发者来说可以完成的离散的小项目，而不应该包含太多涉及到体系结构、核心概念等的抽象信息，因此在“入门”部分只需要提供一个简单明了的概述就可以了。也不要在“入门”部分大谈这个项目如何优秀地解决了问题，这个话题可以放在文档中别的部分进行说明。总而言之，“入门”部分最好是给出一些主要的操作步骤，这样显得开门见山。
- 30 分钟内能够完成：这一点的核心是耗时尽可能短，不宜超过 30 分钟，这个时间上限是考虑到用户可能对你的项目并不了解。这一点很重要，大部分愿意浏览文档的人都是有技术基础的，但对你的项目也仅仅是一知半解。首先让这些读者尝试进行一些相关操作，在收到一定效果后，他们才会愿意花更多时间深入研究整个项目。因此，你可以从耗时这个角度来评估你的文档“入门”部分有没有需要改进之处。
- 有意义的任务：这里“有意义”的含义取决于你的开源项目。最重要的是认真思考并将“入门”部分严格定义为一项任务，然后交给你的读者去完成。这个项目的价值应该在这项有意义的任务中有所体现，不然读者可能会感觉这是一个浪费时间的行为。
提示：假如你的项目是一个分布式数据库，那么达到“整个集群在某些节点故障的情况下可以不中断地保持可用”的目标就可以认为是“有意义”的；假如你的项目是一个数据分析工具或者是商业智能工具，“有意义”的目标也可以是“加载数据后能快速生成多种可视化效果的仪表板”。总之，无论你的项目需要达到什么“有意义”的目标，都应该能在笔记本电脑上本地快速实现。
Linkerd 入门就是一个很好的例子。Linkerd 是一个开源的 Kubernetes 服务网格，当时我对 Kubernetes 了解并不多，也不熟悉服务网格。但我在自己的笔记本电脑上很轻松地就完成了其中的任务，同时也加深了对服务网格的理解。
上面提到的三步过程是一个很有用的框架，对一篇文档“入门”部分的设计和量化评估很有帮助。今后你如果想将你的开源项目产品化，这个框架还可能对实现价值的时间产生影响。
其它核心部分
认真写好“入门”部分之后，你的文档中还需要有这五个部分：架构设计、生产环境使用指导、使用案例、参考资料以及未来展望，这五个部分在一份完整的文档中是必不可少的。
- 架构设计：这一部分需要深入探讨整个项目架构设计的依据，“入门”部分中那些一笔带过的关键细节就应该在这里体现。在产品化过程中，这个部分将会是产品推广计划的核心，因此通常会包含一些可视化呈现的内容，期望的效果是让更多用户长期参与到项目中来。
- 生产环境使用指导：对于同一个项目，在生产环境中部署比在笔记本电脑上部署要复杂得多。因此，指导用户认真使用就尤为重要。同时，有些用户可能对项目很感兴趣，但对生产环境下的使用有所顾虑，而指导和展示的过程则正好能够吸引到这类潜在的用户。
- 使用案例：社会认同的力量是有目共睹的，所以很有必要列出正在生产环境使用这个项目的其他用户，并把这些信息摆放在显眼的位置。这个部分的浏览量甚至仅次于“入门”部分。
- 参考资料：这个部分是对项目的一些详细说明，让用户得以进行详细的研究以及查阅相关信息。一些开源作者会在这个部分事无巨细地列出项目中的每一个细节和边缘情况，这种做法可以理解，但不推荐在项目初期就在这个部分花费过多的时间。你可以采取更折中的方式，在质量和效率之间取得平衡，例如提供一些相关社区的链接、Stack Overflow 上的标签或单独的 FAQ 页面。
- 未来展望：你需要制定一个简略的时间表，规划这个项目的未来发展方向，这会让用户长期保持兴趣。尽管项目在当下可能并不完美，但要让用户知道你仍然有完善这个项目的计划。这个部分也能让整个社区构建一个强大的生态，因此还要向用户提供表达他们对未来展望的看法的交流区。
以上这几个部分或许还没有在你的文档中出现，甚至可能会在后期才能出现，尤其是“使用案例”部分。尽管如此，还是应该在文档中逐渐加入这些部分。如果用户对“入门”部分已经感觉良好，那以上这几个部分将会提起用户更大的兴趣。
最后，请在“入门”部分、README 文件或其它显眼的位置注明整个项目所使用的许可证。这个细节会让你的项目更容易通过最终用户的审核。
花 20% 的时间写作
一般情况下，我建议把整个项目 10% 到 20% 的时间用在文档写作上。也就是说，如果你是全职进行某一个项目的，文档写作需要在其中占半天到一天。
再细致一点，应该将写作纳入到常规的工作流程中，这样它就不再是一件孤立的琐事，而是日常的事务。文档写作应该随着工作进度同步进行，切忌将所有写作任务都堆积起来最后完成，这样才可以帮助你的项目达到最终目标：吸引用户、获得信任。
特别鸣谢云原生计算基金会的布道师 Luc Perkins 给出的宝贵意见。
本文首发于 COSS Media 并经许可发布。
via: https://opensource.com/article/20/3/documentation