Google 文档季案例研究示例

当前阶段
公布的结果。请参阅时间轴

借助此示例创建您自己的案例研究报告。

PicklePlus:记录 GloriousPickle 贡献工具

组织或项目:点击“Glorious Pickle”指向贵组织或项目的主网站

组织说明:GloriousPickle(现行版本 1.2.3,于 2009 年发布的第一版)是获得麻省理工学院许可的库,可用来轻松计算每种可能的腌蔬菜的盐、糖、醋和香料的完美比例,数量范围从一份单小份黄瓜到装运容器小黄瓜不等。

作者:可选项:列出案例研究的作者;如有要求,使用用户名

问题陈述/提案摘要

您尝试通过新的或经过改进的文档解决什么问题?如有可能,链接到您项目网站上的提案页面。

将配料添加到 GloriousPickle 工具成分数据库中既耗时又复杂,而且该工具没有良好的文档记录。许多潜在的贡献者没有使用 Git 或发出拉取请求的经验。这意味着 GloriousPickle 的食材数据存在严重的缺口,并降低了我们的工具的实用性。通过改进添加新配料的文档,我们希望鼓励新的贡献者和更多调料!

项目说明

创建提案

您是如何想出 Google 文档季的提案的?贵组织是采用什么流程来决定创意的?您是如何征求和采纳反馈的?

GloriousPickle PickleDocs SIG 通过 Google 开放源代码计划办公室的推文了解到 Google 文档季计划。SIG 在每两周一次的会议上讨论了该计划,并同意拟定提案。SIG 的两名成员(@KimChiCook 和 @Dillicious)自愿参与拟定提案草稿,供下次会议审核。

PickleDocs SIG 就提案草稿达成一致后,系统会向范围更广的项目发送电子邮件以征求反馈。14 位社区成员提供了反馈,其中包括原料添加 API 的维护者 @GloriousPicklePat。@GloriousPicklePat 自告奋勇成为这项计划提供的资源。

在讨论和整合收到的反馈后,该提案被送交 GloriousPickle 项目指导委员会进行投票。GPPSC 的所有 5 位成员都对提交提案和申请投了 +1 票,并且 @VinegarViv 同意帮助创建参与该计划和监管付款所需的 Open Collective 帐号。

预算

在预算中加入一个简短的预算部分。您是如何估算这项工作的?是否存在任何意外支出?您最终的开支是否少于获赠的赠金?您是否正确分配了资金,或者您是否为某些项目设置了更多/更少/不必要的预算?除了 Google 文档季之外,您是否有其他可以使用的资金?

GloriousPickle PickleDocs SIG 的两名成员(一位在欧洲,一位在阿根廷)担任技术文档工程师。他们帮助我们估算了工作,并比较了他们之前完成的草稿提案工作,发现了类似的项目预算。此外,我们还为该项目分配了 2019 年 PicklePals 大会上的 1000 美元无限制赞助资金。

我们的技术文档工程师在受野火影响的区域,失去了家中网络的访问权限,因此花了一笔不可预知的费用,帮他们租借了 Wi-Fi 热点。最终,我们向参与者送出的 T 恤数量也比计划少,所以平衡了。

此外,我们还决定为 GloriousPickle 贡献者 @Piccalily 提供报酬(她曾是平生平生的专业文案编辑),以帮助其进行文案编辑和校对。

参与者

此项目的工作人员(如果参与者要求,请使用用户名)?您是如何找到并聘请技术文档工程师的?您是如何找到其他志愿者或付费参与者的?他们担任了哪些职务?是否有人退出了?您从招聘、沟通和项目管理方面学到了什么?

参与此项目的核心团队是:

  • @Dillicious、@KimChiCook (PickleDocs SIG)
  • @Piccalily(文案编辑器)
  • @GherKen、@VinegarViv(管理员帮助、GPPSC)
  • @BBChips、@GloriousPicklePat(主题专家)
  • Sam Scribe(技术文档工程师)

我们在 Google 文档季 GitHub 代码库列表中找到了 Sam Scribe。我们认为他们的经历(Sam 曾在一本烹饪杂志工作,还曾为网站撰写过文档)与我们的项目非常契合。Sam 参加了每两周一次的 PickleDocs SIG 通话,并与我们讨论了该项目,并提出了一些非常有价值的建议,并已纳入到提案中。我们还通过 SIG 成员的网络联系了另外两位已知的技术文档工程师,但在计划执行期间,这两位都没有人接听。

由于小萨的时区与 PickleDocs SIG 的大多数成员只有几小时的重叠时间,因此我们在论坛上向在 Sam 所在的时区熟悉原料添加过程的 Picklers 发来电话。@BBChips 自告奋勇为 Sam 回答了各种问题,并在需要时帮助他们寻找其他专家。@GloriousPicklePat 也志愿帮助 Sam 了解该工具的底层架构以及 API 可能显示的错误消息,并提供了 GitHub 和 Git 帮助。

很遗憾,在计划进行到一半时,@VinegarViv 不得不出于个人原因退出该项目。GPPSC 成员 @GherKen 主动处理管理和付款问题。

在一些错过的问题后(GloriousPickle 使用免费的 Slack 实例,有时讨论进展太快,以至于滚动归档限制,以至于我们时常丢失对话),我们了解到应该将正在运行的问题列表保存在一个共享文档中(我们使用了共享的 Google 文档)。PickleDocs SIG 成员在每次会议前都进行了检查,并确保在会议结束前获得答案。对于紧急问题,Sam 直接 ping @BBChips。

我们与 Sam 和 Sam 的合作非常愉快,不仅更新了 GloriousPickle 文档,自己也成为了一名狂热的选择器!

时间表

简要概述项目的时间表(如果项目进行中,请指明预计结束日期或中间里程碑)。

在我们等待 Google 文档季计划公布活动期间,PickleDocs SIG 成员搜索了我们认为对 Sam 有用的所有过往工作。在一个月内,我们发现了早些时候更新停滞不前的文档的一些备注,还仔细研究了 Google opendocs 代码库中的文档成熟度审核资料的部分内容。

我们获选参加 Google 文档赛季的消息后,Sam 和 PickleDocs SIG 会面,共同制定了一份粗略的日程安排:

阶段 完成者
查看文档审核日志 5 月 7 日
摩擦日志 3 应用场景 5 月 14 日
通过 @GloriousPicklePat 和 @BBChips 查看摩擦日志,解答疑问 5 月 28 日
更新后的文档用例 1 的初始草稿 6 月 25 日
用例 1 草稿已由 @GloriousPicklePat 和 @KimChiCook 审核 7 月 2 日
更新后的文档用例 2 的初始草稿 7 月 2 日
用例 2 草稿已由 @GloriousPicklePat 和 @Dillicious 审核 7 月 9 日
更新后的文档用例 3 的初始草稿 7 月 9 日
用例 3 草稿已由 @Dillicious 和 @KimChiCook 审核 7 月 16 日
在所有用例中得到回答的所有查询 7 月 30 日
PickleDocs SIG 的大部分活动都在 8 月 1 日至 20 日休假 --
开始在社区中测试新文档(以草稿形式在 GloriousPickle 网站上发布的文档) 8 月 21 日
纳入测试反馈 9 月 10 日
复制编辑和校对新文档 9 月 17 日
文档的草稿状态已移除,文档已正式发布 9 月 28 日
更新所创建的文档的流程 11 月 1 日
已创建此案例研究 11 月 8 日
已提交案例研究 11 月 16 日

在我们的提案预算中,我们估计技术文档工程师每周要花 10-15 个小时来处理我们的项目。Sam 保留了视频使用时间的记录,平均每周平均有 11.5 小时。

成果

创建、更新或以其他方式更改了哪些内容?附上指向已发布文档的链接(如果有)。提案中是否有任何交付成果尚未创建?请列出这些建议。

其中记录了三个主要用例,并提供了完整的用户方法指南:

如何向 GloriousPickle 添加新成分

如何向 GloriousPickle 添加变体成分

如何更新或更正 GloriousPickle 中的成分

这些指南还包含新的拉取请求模板,以便您更轻松地贡献数据。

此外,在项目期间,Sam 创建了一个关于自己学到术语的小型 Pickle 术语表,该术语表也发布在 GloriousPickle 项目网站上。

我们在 Project Wiki 中添加了关于更新这些用户方法指南的说明。

我们之前为 GitHub 新用户创建了一个备忘单,以帮助他们使用我们的流程和工具,但在查看可用的资源后,我们就可以复制另一个项目的备忘单了。

指标

您选择了哪些指标来衡量项目成功与否?您能否收集这些指标?指标与项目预期成效的相关程度是好还是差?自提案之后,指标是否发生了变化?

在我们的方案中,我们提出了两个指标:

  • 与食材相关的拉取请求的数量
  • 来自新贡献者的拉取请求数量

在 9 月份(自草稿文档发布以来的第一个整月)中,与成分相关的拉取请求数量增加了 5%(从 8 月 20 日增加到 9 月 21 日),我们发现有 3 位新贡献者总共发出了 4 次拉取请求(而 8 月有 2 位新贡献者发出了 2 次拉取请求)。我们计划每月跟踪这些指标。

从 1 月 1 日开始,我们还将跟踪总共做出三次以上贡献的贡献者数量,从文档发布后的季度开始。

有趣的是,我们相信这个新文档在帮助新的贡献者添加到 GloriousPickle 成分数据库方面发挥了重要作用 - 一位新贡献者在其 PR 的评论中提到,他们之前尝试过,但由于不了解流程而未完成更新。

按需

哪些方面表现较好?有什么意外情况?您遇到了什么障碍或挫折?您是否认为自己的项目成功?为什么?(如果为时过早,请说明您预计何时能够判断项目是否成功。)

我们对 Google 文档季的成果非常满意,并认为该项目取得了成功。新文档清晰明了且很有帮助,并且我们已看到与食材相关的拉取请求数量和来自新贡献者的拉取请求数量有所增长。

此外,我们非常高兴地看到,几乎整个 GloriousPickle 社区都参与了进来,他们就原始方案给出了反馈,并测试了草稿形式的新文档。

我们确实遇到了一些意想不到的障碍 — 我们很庆幸 Sam 所在州的野火没有造成任何比互联网中断更严重的损失!此外,对于 @VinegarViv 从项目中失去参选资格,我们深表遗憾;祝她和她的家人一切顺利,希望很快能再次见到她。

直到 Sam 开始编写相关文档后,我们才意识到,对于那些刚开始参与我们项目的人而言,没有匹克菜背景的人对多少与泡菜相关的术语和首字母缩写词感到陌生。不过,Sam 建议将每个不熟悉的术语都列出来,并通过自己的研究以及向社区成员寻求解释和引用来解释这些术语。这份 Pickle 术语库对于未来欢迎更多人加入 Pickle 社区有很大帮助。

摘要

用 2-4 段文字总结您的项目经验。重点介绍您学到的知识,以及以后您希望做出哪些改变。对于利用文档解决类似问题的其他项目,您有什么建议?

总而言之,我们的经历很棒!我们实现了文档交付,指标似乎符合我们的目标。

这个项目之所以取得成功,很大程度上是因为我们能够与技术文档工程师 Sam Scribe 合作,这非常幸运。[我并未撰写此内容 - Sam] 虽然 Sam 没有使用 GitHub 的背景,也没有使用 GitHub 的经验。但作为一名经验丰富的技术文档工程师,他们能够自如地深入了解新的主题、提出问题和开展研究。Sam 很快学到的不仅仅是我们的项目工具(我们用看板来跟踪工作进展),还学到了我们的泡菜笑话!我们非常高兴 Sam 发现了这种腌制虫,并在社区中将它们“装瓶”起来。

我们建议其他项目执行以下操作:

  • 提案内容要简洁且易于管理。(我们最初希望在提案中添加关于将 Estimator 与工业批量腌制机械配合使用的 Estimator 的文档,但后来才有的原因是,我们的一位深度参与开源匹克机械的社区成员正准备在该计划期间撰写她的博士论文。)最后,我们的工作量太大,让 Sam 一直忙!
  • 善用人脉,寻找技术文档工程师。向社群中的每个人寻求建议。虽然我们在 Google 文档 GitHub 季中发现了 Sam,但对于与他们合作的信心,我们还是有信心,因为在申请期间,我们与不少人交流过。
  • 欢迎您的技术文档工程师加入您的社区!Sam 告诉我们,GloriousPicklers 的热情态度让大家很容易提问。
  • 帮助您的技术文档工程师掌握开源技能。Sam 以前从未使用过 Git,但在学习了几个教程后,他们很快就掌握了使用技巧。起初,Sam 担心自己可能会从社区获得多少反馈以及如何采纳,但通过我们社区的“粗略共识”模式(“所有问题都得到解决,但未必能解决”,Sam 才会达成共识),这让 Sam 充满信心地利用自己的技术写作专业知识解决批评意见。

附录

如果您想要链接到其他资料(例如,您创建了一份与技术文档工程师合作的合同,您想分享该合同、用于文档项目的模板或其他开放文档资源,则可以在此列出并链接到这些资源)。您同样可以在附录中列出您使用的任何文档工具或资源的链接,或者添加上述可能不适用的致谢或致谢的链接。

确认

我们的团队衷心感谢以下人员和事情:

  • @Dillicious 想要感谢她的搭档以及低保真嘻哈音乐电台
  • @KimChiCook 感谢他教他如何泡菜
  • @Piccalily 想向 Chicago Manual of Style Online 致谢
  • @GherKen 想感谢他的三个孩子吃下他能做的所有泡菜
  • @VinegarViv 感谢团队的其他成员对她下台的积极配合
  • @BBChips 想感谢市面上最好的非腌制食品,即 Tunnock's Caramel Wafers
  • @GloriousPicklePat 衷心感谢 PickleDocs SIG 参与此项目
  • Sam Scribe 想要感谢整个 GloriousPickle 社区,特别是在 2021 年夏季罐头短缺期间给他们寄送罐装罐的 Picklers,他们一开始就开始品尝很多美味的泡菜了!