7.3 KiB
编写对社区真正有用的文档
成功和可持续的项目，与那些消失无踪的项目有什么不同？答案是——社区。社区是开源项目的发展动力，而文档是构建社区的基石之一。也就是说，文档的意义不仅仅在于文档本身。
建立好的文档可能很困难。用户不愿意阅读文档，因为它不易查找，它很快就过时了，它冗长，或者它不全面。
开发团队不写文档，因为他们陷入了“对我来说很明显，所以对所有人都很明显”的陷阱。他们不写，因为他们忙于开发项目。要么是事物发展得太快了，要么是他们开发得还不够快。
但是好的文档仍然是团队和项目之间最好的沟通工具。考虑到项目随着时间的推移往往会变得更大，这一点尤其重要。
文档可以是团队或公司内部的唯一真理。这在协调人们朝着共同的目标前进，以及在人们转移到不同的项目时保留知识方面非常重要。
那么，要如何为一个项目写出合适的文档，并与正确的人分享呢？
什么是成功的社区文档？
要想在你的社区文档编写中取得成功，你需要：
- 规划你的路径
- 使其清晰简单
- 灵活变通，根据具体情况调整路径
- 做版本控制
灵活并不意味着混乱。许多项目之所以成功，就是因为它们组织得很好。
James Clear（《原子习惯》 的作者）写道：“你并不是提升到了你目标所在的水平，而是降低到你整个系统所在的水平。”一定要组织好过程，使水平足够高，才能取得成功。
设计流程
文档本身就是一个项目。你可以把写文档当作写代码一样。事实上，文档可以是一个产品，而且是一个非常有价值的产品。
这就意味着你可以采用与软件开发相同的流程：分析、需求、设计、实现和维护，把文档作为你的一个流程对待。
在设计流程时，要从不同的角度考虑。同一份文档不一定适用于所有人。
大多数用户只需要了解项目的概况，而 API 文档则更适合开发者或高级用户。
开发者需要了解库和函数的文档。用户则更需要看到示例、操作指南和项目与其他软件的架构关系。
总之，在创建任何流程之前，你必须确定你需要什么：
- 关注的群体： 包括开发者、集成者、管理员、用户、销售、运营、高管
- 专业水平： 要考虑到初级、中级和高级用户
- 详细程度： 既要有高层级的概述，也要有技术细节，所以要考虑如何呈现这些内容
- 路径和入口： 人们如何找到文档，如何使用文档
当你思考这些问题时，它可以帮助你构建你想通过文档传达的信息的结构。它定义了文档中必须包含的内容的清晰指标。
这是如何围绕文档建立一个流程的方法。
编码约定
代码本身应该有意义。文档应通过良好的类名、文件名等来表达出来。通过思考以下内容，创建通用的编码标准和自我注解的编码过程：
- 变量命名约定
- 通过使用类、函数命名方案使名称易于理解
- 避免深度嵌套，或根本不嵌套
- 不要简单地复制和粘贴代码
- 不应使用长方法
- 避免使用幻数（改用常量）
- 使用提取的方法、变量等
- 使用有意义的目录结构、模块、包和文件名
开发时测试
测试不仅仅是关于代码应该如何工作。它还涉及如何使用 API、函数、方法等。编写良好的测试可以揭示基本用例和边缘用例。甚至还有测试驱动开发的实践，专注于在代码开发之前创建测试用例（应该测试什么以及如何测试的分步场景）。
版本控制
版本控制（即使是对文档进行版本控制）可以帮助您跟踪更改的逻辑。它可以帮助您回答为什么这么修改。
确保提交期间的注释解释为什么进行更改，而不是进行了哪些更改。
编写文档过程越吸引人，就会有更多的人参与其中，为它添加创造力和乐趣。您应该通过以下方式考虑文档的可读性：
- 软件代码约定
- 图表和图形（也通过文字进行解释）
- 思维导图
- 概念图
- 信息图表
- 图片（突出显示重要的部分）
- 短视频
通过使用不同的交流方式，您可以提供更多的方式来参与文档。这有助于防止误解（不同的语言，不同的含义）和有助于通过不同的学习方式进行学习。
以下是一些用于创建文档的软件工具：
- Javadoc、Doxygen、JsDoc等： 许多语言都有自动化的文档工具，以帮助捕获代码中的主要功能
- Web 钩子和 CI/CD 引擎： 允许持续发布文档
- Restructured Text，Markdown，Asciidoc： 文件格式和处理引擎，帮助您从纯文本文件中生成美观且实用的文档
- ReadTheDocs： 是一个可以和公共 Git 存储库联动的文档托管主机
- Draw.io， LibreOffice Draw，Dia： 制作图表，图形，思维导图，路线图，计划，标准和指标等
- Peek，Asciinema： 记录终端命令操作
- VokoscreenNG： 录制屏幕和鼠标点击操作
文档很重要
编写文档的过程和协议与项目本身同样重要。最重要的是，它把项目的信息和项目的创造传达到位，更加令人兴奋。
快速进入项目和流程，以及了解一切是如何工作的，是文档一个重要的功能。它有助于确保众人持续参与。通过在团队中构建一种“语言”，可以简化流程，更清晰地理解所要做的事情。
文档旨在传达价值，即无论是通过团队成员还是通过应用程序的用户的言行，来展示出某些东西。
要将这个过程视为一个连续的整体，并在其中融合使用沟通、流程和文档的方式。
文档是一种沟通手段。
via: https://opensource.com/article/23/3/community-documentation
作者：Olga Merkulova 选题：lkxed 译者：alim0x 校对：校对者ID