什么是软件项目的优秀文档？

图片来源：

rawpixel.com。CC0。

开放地理空间 (OSGeo) 基金会最近参与了 Google 的首届 Season of Docs，其中 Google 赞助了资深技术作家为开源项目做贡献。OSGeo 是大约 50 个地理空间开源项目的伞形组织。多年来，我为其中许多项目做出了贡献，最近共同指导了 Google 分配给 OSGeo 的两位 Season of Docs 技术作家。

我们在参与过程中发现，像许多开源项目一样，我们对以下方面知之甚少

我们的文档状态
我们的目标
我们的优先事项
我们面临的挑战的细节
如何改进

我们发现

保持技术文档的更新是多么困难
创建优秀文档需要来自多个角色的技能
与软件开发相比，开源的文档和编写流程尚不成熟

这是一个令人兴奋的问题领域，充满了有待解决的高价值挑战。这让我想起了开源的早期，那时它在商业领域流行起来之前。

技术作家应该做什么？

开源社区欢迎技术作家改进我们的文档，并表示迫切需要这样做，但发现很难确切地说明需要修复什么

人们解释说，他们的项目文档通常在文档发布之间没有更新。
一些项目有尚未记录的新功能。
其他项目有 issue 列表，整理了观察到的缺陷，但没有进行系统的审查。
大多数人观察到文档是由没有接受过正规技术写作培训的开发人员创建的。
许多人指出，他们的英文文档是由非英语母语人士编写的。

但是我们应该从哪里开始呢？我们需要决定我们想要什么以及我们应该首先做什么。

定义优秀的文档

然后我们意识到我们没有“优秀文档”的良好定义。对于我们的软件项目，我们有一个全面的孵化过程来评估软件和项目社区的成熟度，但我们找不到类似的指标来定义“优秀文档”。因此，我们启动了 Good Docs Project，以整理“记录开源软件的最佳实践模板和编写说明”。这帮助我们定义了我们的目标，并确定了我们可以利用现有资源实现的目标的优先级。

文档审计

一旦我们知道优秀文档是什么样的，我们就可以审计项目文档的状态

我们有什么文档？
它是否涵盖了所有功能？
它是否涵盖了最终用户的需求？
文档质量好吗？

我们发现，与它们描述的软件质量相比，我们的 OSGeo 文档的质量、时效性和完整性尚不成熟。

众人拾柴火焰高

在研究开源项目的文档需求时，很明显，编写优秀的文档需要多种技能。理想情况下，文档团队可以访问

一位对所描述软件有深入了解的开发人员
一位可以结合应用领域背景解释应用软件的用户
一位了解学习原则的教育工作者
一位了解如何构建材料的信息架构师
一位写作清晰简洁且语法良好的作家
一位以英语为母语的人（对于英文文档）
一位擅长将文档翻译成多种语言的翻译人员
一位可以设置文档构建管道的 DevOps 人员
一位社区建设者、协调员和协调人，他们可以激发集体行动，捕捉帮助意愿，并帮助所有这些不同角色进行协作

技术作家通常对大多数这些领域都有高层次的理解，他们的技能往往被低估和未被充分利用，特别是当他们被含糊地指示“只是清理语法和内容”时。

然而，最好的文档通常受到多个利益相关者的影响。这可以通过使用模板在领域、时间范围、项目和组织之间进行协作来部分实现。

记录开源项目的工具很痛苦

我们在尝试在软件和写作工具集之间转换时遇到了很大的痛苦。我们喜欢 Git 的版本控制，对笨拙的 Markdown 界面感到沮丧，并且希望可以访问 Word 和 Google Docs 中的编辑和审阅工作流程，以及 Grammarly 等语法和句法插件工具。Transifex 等翻译工具也很酷。

有人可以编写一个应用程序来解决这个用例吗？这里面是否有一个未来 Google Summer of Code 的想法？

OSGeo Season of Docs 期间的成就

我们为 OSGeo 参与 Google Season of Docs 期间的成就感到非常自豪。我们分配的技术作家提高了我们现有文档社区的效率，我们的文档社区提高了这些技术作家的效率

Felicity Brand 与 OSGeo 的大约 50 个开源项目合作，更新 Quickstarts，作为我们 OSGeoLive 软件发行版的一部分。
Swapnil Ogale 直接与 GeoNetwork 的文档团队合作，审计文档的广度和质量，为未来的文档设置模板，并更新许多文档。

更进一步

我们启动了 Good Docs Project，以建立“记录开源软件的最佳实践模板和编写说明”。
与 OGC 和 ISO 空间标准社区合作，我们启动了一个 OSGeo Lexicon 项目，以协调 OSGeo 环境中使用的术语的官方定义。这将把最佳实践定义应用于以前随意编写的词汇表。
我们对 OSGeo 最成功的项目之一 QGIS 面临的文档挑战进行了深入分析。令人惊讶的是，它最大的问题不是缺乏技术作家或复杂的工具（尽管它们是因素）。关键问题集中在
- 未能充分捕捉社区的良好意愿和帮助意愿
- 缺乏方向
- 难以跟上快速发展的软件基线
- 写作专业知识不足
- 技术入门门槛高
- 文档和培训在核心项目之外生成
- 笨拙的文档工具和流程