2021 年案例研究报告

当前阶段
2021 年 Google 文档赛季计划已于 2021 年 12 月 14 日结束。请参阅时间轴

注意:此报告汇总了原计划申请和组织最终案例研究中的数据。“2021 文档季”结果页面中提供了完整的案例研究链接。

关于文档季

Season of Google 文档是由 Google Open Source Programs Office 管理的可持续发展计划。文档季的目标如下:

  • 为开源项目提供支持,以通过文档解决项目问题
  • 为技术文档工程师提供获得开源经验的机会
  • 提升人们对开源、文档和技术写作的认识
  • 在开源文档中收集并分享有效指标的相关信息

如需详细了解《文档季》,请访问该计划的网站

2021 年计划概览

2021 年计划变更

在 2019 年和 2020 年,组织和技术文档撰写者分别申请了“文档季”计划,而技术文档撰写者则按“文档季”计划管理员与组织进行匹配。组织为技术文档工程师提供了指导,让他们根据各自的地理位置获得工作奖金。该计划衡量了技术文档撰写人员、导师和组织管理员对参与计划的满意度,但并未衡量文档方面的成效。

2021 年,Season of Google 文档团队对计划进行了重大变更,将工作重心转移到衡量文档成果上,并为组织和技术文档撰写人员提供了更大的灵活性。

  • 应用了项目提案(包括预算和建议的指标)的组织
  • 技术文案不再通过 Google 申请与组织匹配,而是直接应用于已获批准的组织
  • 入选的组织通过 Open Collective 获得补助,用于支付技术文档撰写费用
  • 技术文档工程师的薪酬由组织设定
  • 各组织提交了最终评估和案例研究,并回答了跟进调查问卷

2021 年总体发现结果

组织

  • 2021 年计划的变化导致申请的组织减少(2021 年申请的组织比 2020 年减少了 30%),但 2021 年的组织管理员对该计划的满意度略高于 2020 年的管理员 (93% 对比 91%)

问题、文档类型和指标

  • 大多数项目侧重于创建文档以减轻维护人员的负担(通过减少问题/问题)和/或提高项目参与率(让项目用户或贡献者参与进来)。
    • 在被接受的组织中,有 50% 创建了教程或方法指南内容。
    • 超过 50% 的被批准组织认为其当前文档缺乏、无组织的或过时。
  • 项目通常希望通过互动来衡量文档的有效性,特别是减少引发的问题,增加访问文档和参与项目的访问者。
  • 截至 2022 年 11 月,在 30 个项目中,有 25 个项目响应:
    • 18 个项目表示他们达到了原始指标
    • 5 个项目达到了修改后的指标
    • 2 个项目表示目前还为时过早

参与计划

  • 对于组织管理员来说,招募、雇用和支付技术文档工程师是该计划中最困难的部分。
  • 截至 2022 年 11 月,在 30 个组织中,有 24 个做出了回应:
    • 有 18 个组织仍在与其 Season of Google 文档的技术文档工程师合作(以持续贡献者或问题解答资源的身份)
      • 4 个组织以付费角色与其 Season of Google 文档的技术文档撰写者合作

2021 年亮点

  • 多个项目都表示,其技术文档工程师打算在 Google 文档季计划结束后继续推进他们的项目
  • Metanorma 应聘了许多符合条件的技术文档工程师,因此他们找到了补贴资金来聘请另外一位作者来与支持 Google 文档的剧季一起工作。
  • Moja Global 发现社区非常热衷于文档内容,并成立了一个新的文档工作组,允许更多贡献者参与项目文档撰写

2021 年数据总结

2021 年,有 82 个组织申请了该计划,30 个开源组织获准加入该计划。(有关选择条件,请参阅创建应用指南。)如需查看完整的参与组织列表,请访问文档季节网站。所有 30 个获认可的组织都提交了最终的案例研究报告,以完成其参与 2021 年计划的资格。

组织简介

参加了 2021 文档季的各组织代表了各种各样的开源项目。2021 年的同类群组包括:

  • 大型语言项目,例如 JuliaPerlR
  • 教育、气候、金融技术、医疗保健、图书馆服务、机器学习、质谱、公共合约和机器人领域的项目
  • 以开发者为中心的项目,包括混乱工程工具、模糊测试工具、聊天机器人 SDK、软件组合分析流水线、性能监控工具和可视化编程工具
  • 文档工具(例如 RedoclyMetanorma)的文档项目

Python 生态系统项目是最大的子类别。2021 年的同类群组包括 ArviZ、NumPy、MicroPython、PyMC3、PyTorch-Ignite 和 SymPy。

我们未收集项目的任何元数据(例如成立日期、贡献者的地理分布、贡献者数量或用户群规模)。

我们要求项目指明它们使用的开源许可。

一个条形图,显示使用各个 OSS 许可的项目数:Apache 2.0:10 个程序;3 子句 BSD:5 个程序;MIT:5 个程序;GPL 2.0:4 个程序;LGPL 2.1:4 程序;Mozilla 公共许可 2.0:3 个程序;艺术、Boost 和 2 子句 BSD:

2021 年组织列出的文档问题是开源项目和一般技术文档中非常常见的问题。

组织希望通过 2021 年计划解决的首要问题包括:

一个条形图,显示组织报告的问题:对于项目的各个具体用例,缺少文档:14 个项目;文档杂乱:14 个项目;文档过时:6 个项目;文档不一致:3 个项目;文档需要转换为其他工具、平台或格式:2 个项目

请注意,组织可能会报告多个文档问题。有关详情,请参阅 2021 年 Google 文档季结果页面,其中链接到每个组织的完整案例研究。

创建的文档类型

教程是 2021 年案例研究中最常提及的文档类型。

一个条形图,显示已创建的文档类型:教程:9 个项目;方法指南:6 个项目;使用入门:3 个项目;示例:3 个项目;参考:3 个项目;API 文档、视频、快速入门、模板、着陆页:每个项目 2 个项目

案例研究中提及的其他文档类型包括文档即代码流水线、图表、术语表、样式指南、常见问题解答、国际化、Codelab、内容模型、模块、概念文档、错误消息、用户研究、自述文件、知识库

其中一些类别模糊不清,单个文档项目可能包含多种文档类型或功能。

在规划文档类型的指南时,我们特别引用了图表框架并提及的多个项目。

有关详情,请参阅 2021 年 Google 文档季结果页面,其中链接到每个组织的完整案例研究。

预算

2021 年,平均预算请求为 10,200 美元,中位数为 10,000 美元。只有三个组织申请并获得尽可能高的补助金额(1.5 万美元),还有三个组织申请了可能的最低金额(5,000 美元)。

指标

项目在案例研究中概述了他们用来衡量文档项目成功的指标。

建议最多的指标为:

显示文档成功指标的条形图:项目问题/问题较少:13 个项目;文档/文档使用人数增加:9 个项目;更多贡献者/拉取请求:8 个项目;更多文档拉取请求/贡献:7 个项目;创建的文档总数:5 个;提高了文档满意度(通过问卷调查);项目使用率有所提高;项目使用率有所提高;已转换项目的 2 个项目更直接,涉及的文档总数所占百分比更高;文档总数所占百分比:3 个总文档数百分比:

其他提议的指标包括 GitHub 星星、页面停留时间、邮寄名单转化、定性用户测试、论坛参与者数量、合作伙伴/志愿者/集成人数

由于完成技术写作项目与提交案例研究之间的时间间隔很短,因此 2021 年的大多数同类群组无法收集足够的数据来确定其是否满足了初始指标。

有关详情,请参阅 2021 年 Google 文档季结果页面,其中链接到每个组织的完整案例研究。

与技术文档工程师合作

2021 年,“文档季”计划发生的最大变化涉及项目与技术文档撰写者的合作方式。在之前的几个赛季中,技术文档工程师直接向 Google 提出申请,由计划管理员为项目安排匹配,并直接从 Google 获得固定奖金。

2021 年,技术文档工程师直接为项目和项目设定薪酬预算,通过 Google 文档赛季 Open Collective 资助支付款项。

参与 2021 年计划的大多数项目在招聘或聘用技术文档工程师方面经验非常少或根本没有经验,并且许多项目都指出流程中的这一部分需要更多支持。根据此反馈,Sason of Google 文档团队向收视指南添加了关于创建技术文档撰写协议的文档

招聘建议

他们请项目为其他有兴趣参与 Google 文档季的项目提供建议。最重要的招聘建议是:

  • 尽早向技术文档工程师分享招聘材料,即便您还未获准加入本计划。邀请观众推荐可能的候选人。
  • 在项目渠道外广泛分享。使用包容性的语言,并直接鼓励背景少数群体的候选人申请。
  • 了解哪些工具对您的文档创建流程至关重要,并招募有使用这些工具的技术文档工程师。
  • 就可交付成果和里程碑、沟通渠道和签到以及付款流程和时间安排为技术文档工程师设定明确的预期。
  • 考虑投资于社区成员,并使用“文档季”的技术文档撰写人员提供指导和指导,帮助他们成长为技术文档撰写者。
  • 在计划期间,为入职培训技术文档工程师、回答问题和提供支持的时间留出比预期更多的时间,特别是如果技术文档工程师以前在项目领域没有相关经验,更是如此。
  • 记录招聘、招聘和入职培训流程,以供未来项目参考。

一个条形图,显示技术文档撰写者的候选人来源:直接应用到计划:7;SoD GitHub 或上一个 SoD 参与者:4;撰写 Google 文档 Slack 或社区成员:3 人;通过招聘信息网站(Upwork、LinkedIn)应用、Google 编程之夏或 Code-In 校友:每个 2

(注意:并非所有项目在其案例研究中提到的都是招募技术文档工程师候选人的项目。)

与技术文档工程师合作时的常见问题

一个条形图,显示技术文档写手相关问题:台湾地区用户流失:8 个项目;沟通问题:6 个项目;台湾地区入职流程:4 个项目;台湾地区招聘;招聘或付款;项目工具设置:每个项目 3 个项目

由于新冠或其他疾病,或者与疫情相关的家庭责任,多个项目的技术文档工程师不得不放弃工作。一些项目报告了涉及时区不一致或互联网连接问题的通信问题。

项目发现他们低估了加入社区或设置项目的文档工具链所涉及的困难。

有些项目因与 Open Collective 的银行业务问题或付款人所在国家/地区有付款限制而出现向技术文档编写人员付款的延迟。

关于 Open Collective 费用的计划文档并不明确:Google 涵盖了 Open Collective 向项目进行初始资金转帐所产生的交易费用,但不包括某些其他付款渠道征收的交易费用(例如货币换算费用)。我们将努力在今后的计划文档中更明确地说明这一点。

跟进调查问卷

作为 Google 文档季计划的一部分,我们邀请了一些项目参与跟进调查。我们在 2022 年 5 月、8 月和 11 月分别发送了三份调查问卷。

一个条形图,显示后续问卷调查的回复数量:5 月调查:13 条回复;8 月调查:21 条回复;11 月调查:12 条回复

后续调查问卷要求项目确认其提案和案例研究链接仍然有效。调查问卷中还包含一些问题,包括项目的成功(取决于他们在其案例研究中设置的指标)、项目技术文档工程师的持续参与和支付的薪酬:

  1. 您还在与季度 Google 文档技术文档工程师合作吗?

显示每个调查问卷中技术文档工程师持续参与的条形图:5 月,6 个项目有技术文档工程师参与或回答问题;1 个项目没有技术文档工程师持续参与。8 月份,有 11 个项目有技术文档工程师持续参与;有 7 个项目没有技术文档工程师参与,还有 3 个项目有技术文档工程师回答问题。11 月份,有 5 个项目报告技术文档工程师不参与互动;有 3 个项目报告技术文档工程师不持续参与;有 4 个项目报告技术文档工程师回答问题。

  1. 如果您的技术文档工程师仍在处理项目,他们是否会获得任何报酬?

一个条形图,显示每份调查问卷中向技术文档工程师报告项目薪酬的项目数量。5 月,有 5 个项目报告称技术文档工程师能凭借持续工作获得报酬;有 4 个项目报告称技术文档工程师无薪。8 月份,有 4 个项目报告他们向技术文档工程师支付报酬,有 7 个项目报告称技术文档工程师无奖金。11 月份,有 2 个项目报告他们向技术文档工程师支付报酬,有 5 个项目报告称技术文档工程师无奖金。

  1. 此时,您是否认为自己的文档项目成功了?

一个条形图,显示根据每项调查问卷中的指标报告成功的项目数量。5 月份,有 6 个项目报告其指标已达标;有 6 个项目表示为时过早,有 2 个项目达到了调整后的指标。8 月份,有 16 个项目报告称指标已达标;3 个项目报告称已达成调整指标;有 2 个项目报告称目前为时尚早。11 月份,有 9 个项目报告的指标已达到上限;有 3 个项目报告称已达成调整指标,但没有任何项目报告称目前还为时过早。

后续问题

与往常一样,我们对开源文档了解得越多,我们想学习的就越多!在接下来的赛季中,我们希望了解:

  • 项目域是否与文档类型选择或指标选择相关
  • 哪些招聘技术文档工程师和入职入职实践对完成项目和留住技术文档工程师最有效
  • 合理安排文档有效性

虽然我们想调查许多问题,但也希望尊重参与“文档季”的开源项目管理员和维护者的时间。该计划的首要任务是协助项目利用文档解决各种问题。