编写对社区真正有用的文档

作者: Olga Merkulova 译者: alim0x

| 2023-04-22 17:28:00   评论: 0

建立良好的文档可能是困难的,但它对有效的沟通至关重要。遵循这个框架来编写并与正确的人分享文档。

成功和可持续的项目,与那些消失无踪的项目有什么不同?答案是 —— 社区。社区是开源项目的发展动力,而文档是构建社区的基石之一。也就是说,文档的意义不仅仅在于文档本身。

建立好的文档可能很困难。用户不愿意阅读文档,因为它不易查找,它很快就过时了,它冗长,或者它不全面。

开发团队不写文档,因为他们陷入了“对我来说显而易见,所以对所有人都显而易见”的陷阱。他们不写,因为他们忙于开发项目。要么是需求变化太快了,要么是开发得还不够快。

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

文档可以是团队或公司内部的唯一真理。这在协调人们朝着共同的目标前进,以及在人们转移到不同的项目时保留知识方面非常重要。

那么,要如何为一个项目写出合适的文档,并与正确的人分享呢?

什么是成功的社区文档?

要想在你的社区文档编写中取得成功,你需要:

  • 规划你的路径
  • 使其清晰简单
  • 灵活变通,根据具体情况调整路径
  • 做版本控制

图片展示了建立文档的整个流程

灵活并不意味着混乱。许多项目之所以成功,就是因为它们组织得很好。

James Clear(《 原子习惯 Atomic Habits 》一书的作者)写道:“你并不是提升到了你目标所在的水平,而是降低到你整个系统所在的水平。”一定要组织好过程,使水平足够高,才能取得成功。

设计流程

文档本身就是一个项目。你可以把写文档当作写代码一样。事实上,文档可以是一个产品,而且是一个非常有价值的产品。

这就意味着你可以采用与软件开发相同的流程:分析、获取需求、设计、实现和维护,把文档作为你的一个流程对待。

在设计流程时,要从不同的角度考虑。不是所有的文档都适用于所有人。

大多数用户只需要一个了解项目概况的文档,而 API 文档则是留给开发者或高级用户的。

开发者需要了解库和函数的文档。用户则更需要看到示例、操作指南,和项目与其他软件相配合的架构概述。

图片展示了编写文档时的不同视角

总之,在创建任何流程之前,你必须确定你需要什么:

  • 关注的群体: 包括开发者、集成商、管理员、用户、销售、运营、高管
  • 专业水平: 要考虑到初级、中级和高级用户
  • 详细程度: 既要有高层级的概述,也要有技术细节,所以要考虑如何呈现这些内容
  • 路径和入口: 人们如何找到文档,如何使用文档

当你思考这些问题时,它可以帮助你构建你想通过文档传达的信息的结构。它定义了文档中必须包含的内容的清晰指标。

下面是如何围绕文档建立一个流程的方法。

编码约定

代码本身应该有意义。文档应通过良好的类名、文件名等来表达出来。通过思考以下内容,创建通用的编码标准和自我注解的编码过程:

  • 变量命名约定
  • 通过使用类、函数命名方案使名称易于理解
  • 避免深度嵌套,或 根本不嵌套
  • 不要简单地复制和粘贴代码
  • 不应使用长方法
  • 避免使用幻数(改用常量)
  • 使用提取的方法、变量等
  • 使用有意义的目录结构、模块、包和文件名

开发时测试

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

版本控制

版本控制(即使是对文档进行版本控制)可以帮助你跟踪更改的逻辑。它可以帮助你回答为什么这么修改。

确保提交期间的注释能解释为什么进行更改,而不是进行了哪些更改。

编写文档过程越吸引人,就会有更多的人参与其中,为它添加创造力和乐趣。你应该通过以下方式考虑文档的可读性:

  • 软件代码约定
  • 图表和图形(也通过文字进行解释)
  • 思维导图
  • 概念图
  • 信息图表
  • 图片(突出显示重要的部分)
  • 短视频

通过使用不同的交流方式,你可以提供更多的方式来参与文档。这有助于防止误解(不同的语言,不同的含义)和有助于通过不同的学习方式进行学习。

以下是一些用于创建文档的软件工具:

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

文档很重要

编写文档的过程和协议与项目本身同样重要。最重要的是,它把项目的信息和项目的创造传达到位,更加令人兴奋。

快速进入项目和流程,以及了解一切是如何工作的,是文档一个重要的功能。它有助于确保众人持续参与。通过在团队中构建一种“语言”,可以简化流程,更清晰地理解所要做的事情。

文档旨在传达价值,即无论是通过团队成员还是通过应用程序的用户的言行,来展示出某些东西。

要将这个过程视为一个连续的整体,并在其中融合使用沟通、流程和文档的方式。

图片展示了文档作为一种沟通的过程

文档是一种沟通手段。

(题图:MJ:document development illustration in high resolution, very detailed



最新评论


友情链接
返回顶部