为你的社区编写真正有效的文档

是什么将成功且可持续的项目与那些消失得无影无踪的项目区分开来？剧透一下——是社区。社区是驱动开源项目的力量，而文档是构建社区的基础模块之一。换句话说，文档不仅仅是关于文档。

建立良好的文档可能很困难。用户不阅读文档，因为文档不方便、过时速度太快、内容太多或内容不足。

开发团队不编写文档，因为他们陷入“对我来说显而易见，所以对所有人来说都显而易见”的陷阱。他们不编写文档是因为他们太忙于让项目存在。事情发展得太快，或者发展得不够快。

但良好的文档仍然是团队和项目最好的沟通工具。考虑到项目往往会随着时间的推移而变得更大，这一点尤其正确。

文档可以是团队或公司内部的单一真理来源。  当协调人们朝着共同目标努力，并在人们转向不同项目时保留知识时，这一点非常重要。

那么，你如何为一个项目编写合适的文档，并与合适的人分享呢？

什么是成功的社区文档？

为了在你的社区中成功编写文档

• 组织你的日常工作

• 使其清晰明了

• 保持灵活性，根据具体情况更改日常工作

• 进行版本控制

图片来源

(奥尔加·梅尔库洛娃，CC BY-SA 4.0)

保持灵活性并不意味着混乱。许多项目之所以成功，仅仅是因为它们组织良好。

詹姆斯·克利尔（《原子习惯》的作者）写道：“你不会提升到你的目标水平。你会下降到你的系统水平。” 务必组织好流程，使水平足够高以实现成功。

设计流程

文档是一个项目。将编写文档视为编写代码。事实上，文档可以是一种产品，而且是非常有用的产品。

这意味着你可以使用与软件开发相同的流程：分析、捕获需求、设计、实施和维护。将文档作为你的流程之一。

在设计流程时，从不同的角度考虑它。并非所有文档都适合所有人。

大多数用户只需要项目的概览，而 API 文档可能最好留给开发人员或高级用户。

开发人员需要库和函数文档。用户最好通过示例用例、逐步指南以及项目如何与他们使用的其他软件配合使用的架构概述来获得服务。

图片来源

(奥尔加·梅尔库洛娃，CC BY-SA 4.0)

最终，在创建任何流程之前，你必须确定你需要什么

• 焦点小组： 这包括开发人员、集成商、管理员、用户、销售、运营、高管

• 专业知识水平：记住初级、中级和高级用户

• 细节程度：既有高层概述的空间，也有技术细节的空间，因此请考虑如何呈现这些内容

• 旅程和入口点：人们如何找到文档，他们如何使用它

当你思考这些问题时，它有助于你构建想要通过文档传达的信息。它定义了文档中必须包含哪些内容的明确指标。

这是围绕文档构建流程的方法。

编码约定

代码本身应该有意义。文档应该通过良好的类名、文件名等来表达。创建通用的编码标准，并通过考虑以下几点来制定自文档化的代码流程

• 变量命名约定

• 通过使用类、函数命名方案使名称易于理解

• 避免深度嵌套，或者根本不嵌套

• 不要简单地复制粘贴代码

• 不应使用长方法

• 避免使用魔术数字（而是使用 const）

• 使用提取方法、变量等

• 使用有意义的目录结构、模块、包和文件

测试与工程并行

测试不仅仅是关于代码应该如何表现。它还关于如何使用 API、函数、方法等等。编写良好的测试可以揭示基本情况和边缘情况。甚至有一种测试驱动开发实践，专注于在代码开发之前创建测试用例（应该测试什么以及如何测试的逐步场景）。

版本控制

版本控制，即使对于你的文档也是如此，可以帮助你跟踪更改的逻辑。它可以帮助你回答为什么要进行更改。

确保提交期间的注释解释了更改的原因，而不是更改的内容。

文档流程越吸引人，就会有越多的人参与其中。为其添加创造性和趣味性。你应该通过使用以下方式来考虑文档的可读性

• 软件编码约定

• 图表和图形（也在文本中解释）

• 思维导图

• 概念图

• 信息图

• 图像（突出显示重要部分）

• 短视频

通过使用不同的沟通方式，你提供了更多参与文档的方式。这可以帮助预防误解（不同的语言，不同的含义）和不同的学习风格。

这里有一些用于创建文档的软件工具

• Javadoc、Doxygen、JsDoc 等：许多语言都有自动化文档工具，以帮助捕获代码中的主要功能
• Web 钩子和 CI/CD 引擎：允许持续发布你的文档
• Restructured Text、Markdown、Asciidoc：文件格式和处理引擎帮助你从纯文本文件中生成美观且可用的文档
• ReadTheDocs：  是一个可以附加到公共 Git 存储库的文档托管平台
• Draw.io、 LibreOffice Draw、 Dia：生成图表、图形、思维导图、路线图、规划、标准和指标
• Peek、 Asciinema：使用命令记录你的终端
• VokoscreenNG：使用鼠标点击和屏幕截图

文档至关重要

记录流程和协议与记录你的项目本身同样重要。最重要的是，使关于你的项目和项目创建的信息令人兴奋。

进入项目和流程的速度，以及理解一切如何运作，是一个重要的特征。它有助于确保持续参与。通过在团队中构建一种“语言”来获得简单的流程和对需要做什么的清晰理解。

文档旨在传达价值，这意味着通过言语和行动来证明某些东西。无论是你的团队成员还是你的应用程序用户，都无关紧要。

将流程视为一个连续体，并使用沟通方式、流程和文档。

图片来源

(奥尔加·梅尔库洛娃，CC BY-SA 4.0)

文档是一种沟通方式。