文档季是由 Google 开源计划办公室 管理的可持续发展计划。文档季的目标是：
- 为开源项目提供支持，以通过文档解决项目问题
- 为技术文档工程师提供获得开源经验的机会
- 提高对开源、文档和技术文档工程的认知度
- 收集和分享有关开源文档中有效指标的信息
如需详细了解文档季，请访问该计划的网站。
2022 年计划概览
文档季的运作方式
在文档季中，组织通过提交项目提案进行申请。项目提案包括：
- 有关组织的信息
- 对项目面临问题的描述
- 项目将如何使用文档来帮助解决问题
- 项目将如何衡量文档的有效性（指标）
- 工作时间表
- 项目预算
- 任何其他信息，例如组织在类似计划中的经验，或有助于文档季管理员了解其项目和问题的任何其他信息
组织被该计划接受后，会直接招聘和聘用自己的技术文档工程师。文档季使用 Open Collective 为组织提供资金，组织通过 Open Collective 向技术文档工程师付款。项目预算和付款是透明的；预算包含在文档季网站上提供的组织项目提案中，付款在文档季 Open Collective 账号中可见。
组织提交案例研究报告后，即被视为成功完成该计划。组织还需要在该计划期间完成每月评估，并在计划完成后的一年内完成三项季度后续调查。
2022 年亮点
“新文档发布后，Casbin 和 Casdoor 的每日访问量几乎翻了一番，跳出率下降了约 30%。”——Casbin
“这个项目的一个令人欣喜的结果是，我们看到 [我们的技术文档工程师] 成长为我们社区的领导者。这两位贡献者现在都在领导工作组和社区会议，并为我们项目的设计和维护做出贡献。”——moja-global
“[GSoD] 帮助我们招聘了两位才华横溢的技术文档工程师，这在常规设置中非常困难。他们继续积极为 OpenMined 贡献开源代码，我们与他们合作的体验非常棒。”——OpenMined
“此外，新手也很容易上手新的手册，了解计算质谱分析。为了说明这一点：CZI 补助金还为历史上处于弱势地位的个人提供津贴，一些获奖者使用新的 OpenMS 手册快速开始了为期六周的实习期，并对新手册给予了积极评价。”——OpenMS
2022 年汇总数据
2022 年，文档季计划从 67 份申请中接受了 31 个项目，其中 30 个项目成功完成了该计划。在 31 个被接受的组织中，有 17 个组织是重复申请者。
31 个被接受的项目聘用了 58 位技术文档工程师。超过 190 位技术文档工程师在文档季 GitHub 代码库中添加了联系信息和作品集链接，表明他们有兴趣参与该计划。
对于 2022 年计划：
- 100% 的组织对申请流程的体验良好
- 100% 的组织对计划网站文档/内容的体验良好
- 93% 的组织对该计划的体验良好
- 90% 的组织认为其文档项目取得了成功
关于组织
参与 2022 年文档季的组织代表了各种各样的开源项目。2022 年的参与者包括：
- 开发工具，例如 AsyncAPI 和 SpyderIDE
- 编程语言和框架，例如 Julia、LFortran、R 和 p5.js
- 科学项目，例如 CERN-HSF 和 SymPy
- 最终用户应用，例如 Mautic、Open Food Facts、Talawa 和 Ushahidi
- 硬件和机器人项目，例如 ExpressLRS 和 Open-RMF
- 数据项目，例如 GeomScale、GeomStats、OpenMined 和 Weaviate
- 云和基础架构项目，例如 cert-manager、NimbleEdge 和 Cilium
我们没有收集任何有关项目的元数据（例如成立日期、贡献者的地理分布、贡献者人数或用户群规模）。
我们确实要求项目指明他们使用的开源许可。
关于文档项目
文档问题
在 2022 年计划中，组织希望通过文档解决的主要问题包括：
请注意，组织可以报告多个文档问题。如需了解更多具体信息，请参阅 2022 年文档季结果页面，其中包含每个组织的原始项目提案和完整案例研究的链接。
创建的文档类型
在 2022 年的案例研究中，操作指南文档是最常提及的文档类型。
案例研究中提及的其他文档类型包括：
- 快速入门
- 术语表
- 常见问题解答
- 知识库
- 组件
- 博客/社交媒体内容
- 维护者指南
其中一些类别比较模糊，单个文档项目可能包含多种文档类型或功能。
如需了解更多具体信息，请参阅 2022 年文档季结果页面，其中包含每个组织的原始项目提案和完整案例研究的链接。
预算
平均预算申请金额为 11,679 美元，中位数为 12,150 美元。有 5 个组织申请并获得了最高补助金（15,000 美元），有 3 个组织申请了最低补助金（5,000 美元至 7,000 美元）。
指标
项目在其案例研究中概述了他们用于衡量文档项目成功与否的指标。
最常提出的指标是：
其他提出的指标包括：
- 更多文档拉取请求/贡献
- 有关文档页面的更多直接反馈
- 页面停留时间
- 提出的问题（作为使用情况的代理）
- 论坛参与者
- 合作伙伴/志愿者/集成数量
- 跳出率降低
- 社区认知度提高。
由于完成技术文档工程项目和提交案例研究之间的时间窗口很短，因此 2022 年的大部分参与者在提交案例研究时都无法收集到足够的数据来确定其初始指标是否已达成。
随着我们在 2023 年收到后续调查的回答，我们将更新本报告，添加有关哪些项目已达成其指标或修订其指标的信息。
如需了解更多具体信息，请参阅 2022 年文档季结果页面，其中包含每个组织的原始项目提案和完整案例研究的链接。
与技术文档工程师合作
在文档季计划中，项目需要直接招聘、面试、聘用和支付技术文档工程师的费用。技术文档工程师可以将自己添加到我们 GitHub 代码库中由文档季维护的目录中，但文档季工作人员不会审核或推荐技术文档工程师。
为开源项目聘用技术文档工程师的最佳实践
我们要求项目分享他们在招聘、聘用和与技术文档工程师合作方面的最佳实践。最常提出的建议是：
招聘
- 减少面试候选人数量，并使用现场实践环节，而不是仅查看简历
- 重视书面和口头沟通能力，而不是对项目语言或工具的熟练程度
- 直接询问技术文档工程师将如何获取与项目合作所需的任何领域知识
- 对项目使命充满热情并认同核心开源价值观的人更有可能在整个项目中保持积极性
- 欢迎来自世界各地的申请人，因为不同的观点和背景将有助于您的项目，但请注意，如果撰稿人和导师分布在太多冲突的时区，可能需要付出大量额外努力才能保持良好的沟通
聘用
- 使用明确列出可交付内容、付款时间表和具体时间承诺的合同
- 如果您的项目有很多未知因素，请添加一个与文档创建分开的发现或研究里程碑
协调和沟通
- 保留会议记录，记录决策，以便参与项目的所有人都能更轻松地了解背景信息和后续步骤
- 明确说明预期沟通方式和频率，无论是每周通话、每日电子邮件还是聊天渠道中的状态更新
- 及时响应并提供清晰的反馈，包括“原因”，而不仅仅是“内容”
- 将技术文档工程师与更广泛的社区联系起来，让他们了解背景信息并宣传他们的工作
流程和工具
- 创建一个文档流程，该流程将持续到文档季计划结束后，并且整个社区都可以参与其中
- 文档审核至少需要与代码审核一样长的时间，并且同样紧张；请确保您预留足够的时间
为了清晰起见，我们对一些建议进行了编辑和缩减。
与 2021 年计划一样，2022 年文档季中的大多数技术文档工程师都是直接向他们合作的组织申请的。
与技术文档工程师合作时遇到的常见问题
在 2022 年计划中，报告与技术文档工程师合作时遇到问题的项目较少。技术文档工程师无法完成该计划是最大的问题，原因包括生病、找到全职工作或无法履行时间承诺。
一个项目报告称，他们的文档项目依赖于 Google 编程之夏 中完成的工作，而这些依赖项难以管理。另一个项目遇到了困难，因为他们的技术文档工程师需要记录的硬件被该工程师所在国家/地区的国防部没收，无法进口。
后续调查
我们将于 2023 年 5 月、8 月和 11 月向 2022 年的参与者发送三项后续调查。收到结果后，我们将更新此部分。
未来问题
与往常一样，我们对开源文档了解得越多，就越想了解更多！
在未来的文档季中，我们希望：
- 收集更多项目元数据，以查找项目年龄、社区规模或语言与文档需求之间的相关性
- 分析文档项目，看看它们是否可以概括为可共享的模板
- 为开源项目中的技术文档工程师面试制定评分标准
虽然我们有很多问题想要调查，但我们也希望尊重参与文档季的开源项目管理员和维护者的时间。该计划的首要任务是支持项目通过文档解决问题。