如何成为文档提交者
最后更新于
最后更新于
警告
本文译者敬告读者，不要在没有耐心（你的提交经常会被忽略一年或更长时间）或准备的情况下参与任何 FreeBSD 文档工作。这也是《FreeBSD 从入门到跑路》的肇因。
原文链接：
作者：BENEDICT REUSCHLING
FreeBSD 文档集包含了面向用户和开发者的各种手册、常见问题解答、特定主题的文章、位于 src 仓库中的 man 页以及主要的 FreeBSD.org 网站。这是新手向 FreeBSD 项目做出初次贡献的一个很好的途径，并且是许多目前仍活跃的开发者的起点。在阅读我们的文档时，人们经常会发现一些需要修正的地方：从缺少逗号，到单词中的拼写错误，再到整个段落过时需要重写。那些不会只是耸耸肩然后无所谓的人，通常会在我们的 Bugzilla 系统上报告这个问题 [https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation] 或者提出补丁来修复问题。虽然后者肯定不是必需的（尤其是对于临时报告和尚不熟悉我们文档工具链的人），但总比后者什么都不做要好。
这不仅仅是发现现有材料中的错误。如果您发现了更简单的做法并能够解释清楚，提交一份包含您工作的 bug 报告。其他人可能会发现我们的手册可以增加更多的图片来帮助说明其中的概念（毕竟，一图胜万语），并可能希望向我们提交他们的草图。更新的截图也属于这一类，并帮助新手通过与自己屏幕上的内容进行对比，确认自己走在正确的道路上。在会议上发放的展示常用 FreeBSD 命令的传单和备忘单也是展示您才华的另一种方式。我提到过我们需要更多的 EXAMPLE 部分在各种用户 man 页面中吗？定期运行链接检查器，检查我们链接的网页，并报告死链（更好的是，找到一个替代位置）。如果您喜欢维基并且在那里进行编辑，加入 Freenode IRC 上的 #freebsd-wiki 组吧。换句话说，让我们惊讶一下（以一种好的方式），并用一些示例展示您对这项工作的认真态度。
无论是什么，文档提交者会接手您的工作（通常是一个补丁或文本描述）并开始处理。如果没有，适当的提醒可能会有所帮助，因为开发者们有很多工作要做。在最简单的情况下（逗号或拼写错误修复），他们会直接修改源代码并提交，您作为原提交者会在提交信息的“提交者：”一行中获得归功。感谢您的贡献，您刚刚让 FreeBSD 文档变得更好！
在其他情况下（当问题变得更复杂或补丁较大时），您也可以在我们的 Phabricator 实例上创建账户 ，并通过这种方式提交补丁（添加文档组或个人作为审阅者）。这使得补丁审阅过程更容易追踪，并能从不同的角度（写作风格、格式等）进行反馈和更新现有补丁。如果您只收到几行反馈，并且这些反馈可能听起来过于苛刻，不要气馁。在大多数情况下，我发现进行审阅的人通常只有几分钟的时间来做这些工作，因此他们的反馈通常简短而直接。如果您不理解我们使用的术语或不知道如何继续进行，不要害怕提问。不要把反馈看得太个人化，因为我们批评的并不是您，而只是代码。我通常会尽量在我的评论中加入一些积极的反馈。“感谢提交补丁”，“好眼力”，“很高兴您花时间报告这个”这类话语可以让提交者感到鼓舞，并愿意将提供的反馈融入他们的代码中，进行下一轮审阅。
随着时间的推移、耐心和一些实践，您将把您的第一个贡献提交到文档树中。感觉不错吧？您可能会把它展示给您的朋友和同事，在社交媒体上发布，甚至从最高的山峰上呐喊出来。我认为人们都渴望在生活中有这样的成功时刻，可以指着某个东西骄傲地说：“看，这就是我干的。”虽然有些人可能会说：“哼，这有什么大不了的”，但请记住，正是基于您的贡献，提交者才接手了这个补丁，并在 FreeBSD 仓库中做出了更改。您已经成为这个有着 30 余年历史的项目的一部分了。而且，这也是一个与人们共同为您关心的事物工作的大好机会。许多人如此喜欢这种体验，以至于他们继续贡献其他补丁。而问题也就从这里开始了……
随着时间的推移，同一个人可能会向文档树提交很多优秀的贡献。从几周内提交大量小补丁，到开创性的、添加大量新材料的工作（以及其中的任何情况）。项目中的人开始注意到这一点。此外，您会认真对待反馈，并以一种建设性和合作的方式与开发者合作。然后，有一天，这种情况发生了：提交者感到烦恼，因为他们正在为您做这些工作，而这些工作您基本上可以自己做。这就是我们所谓的“惩罚”某人并给予提交权限的原因。
文档提交者会创建一个您过去贡献的清单（有些人可能称其为一种特殊形式的“调皮名单”）。这就是为什么我们会在提交信息中的“Submitted by:”字段中收集您的记录。Phabricator 还可以生成您所有审阅互动的漂亮清单。然后，这个清单会被发送到文档工程团队（简称 doceng），该团队负责（除了其他工作外）管理文档提交权限。通常，会附带一份“请让我指导那个人，这样他们可以提交自己的工作，而我可以腾出时间”的请求。该提案会在团队内部进行评估和投票。有时，提交者会组建一个小型小组来更好地覆盖导师和学员之间的不同时间区间（更快的反馈循环）。如果认为有必要，doceng 团队可以选择额外的导师。如果投票结果支持学员，他们会收到通知并获得访问项目资源的权限，必要时可以与文档协作。如果未能授予提交权限，通常会提供反馈，说明缺少的内容（通常是“充实您的贡献记录”），并鼓励在一段时间后再次提出提案。
导师随后会教导新学员所需了解的所有内容：从理解我们的格式规则，如何在手册页发生重大变化时更新 .Dd（文档日期），到他们第一次紧张（通常是手心出汗）的提交。在此过程中，当学员犯错时，导师会提供帮助。指导阶段旨在让学员获得足够的信心，不再犯这些错误，并从导师在项目中积累的丰富经验中学习。学员在社区中的社交互动也是过程的一部分，并且欢迎其他贡献者的反馈（这完成了反馈循环），与社区中的其他成员合作，通常在导师审阅后提交自己提交的补丁。
现代工具如 Phabricator 使得这个过程比通过电子邮件处理要容易得多，虽然电子邮件也能完成这项工作（那是我早期的指导方式），但会花费更多时间。这是一项紧张的工作，但根据我的经验，也是非常有趣的。我见过导师和学员在这个过程中建立了深厚的个人关系，这本身就是一种令人满足的体验。当然，每个学员都不同，但通常我看到的是，导师和学员第一次在会议上见面时，马上就像老朋友一样交谈。
项目中的一些人认为指导不值得花费时间，因为这会剥夺他们自己进行 FreeBSD 工作的时间。虽然这可能是真的，但我发现，我在工作中减少的时间，通过整个项目增加的生产力，多次得到了回报。毕竟，两个人人一起做出更改，而新学员的激情和热情可能会激励您共同进行那项长期拖延的文档更改。指导不是适合每个人，因此没有人被强迫去指导。幸运的是，有足够愿意做这项工作的人员，其中一些人愿意共同指导某人以分担负担。在我的经验中，通常是一个群体在指导学员，而不仅仅是一个人。反馈和鼓励不仅仅来自导师，而是来自更广泛的社区，这鼓励学员逐步拓展自己的网络。我看到过很多曾是我学员的人，他们进入了我不熟悉的项目领域，因为我在该领域的知识有限。但这对整个项目来说是一个极大的好处。
无论如何，指导期可能会持续一段时间，这取决于可用的工作量、时间限制以及学员和导师的参与情况。过了一段时间，导师可能会觉得他们只是批准更改，而不再需要做太多的修正，学员也已学到了所有必要的知识。在学员同意的情况下，他们将被释放，成为与其他人一样的平等文档提交者。我个人在告别信息中鼓励我的前学员，如果他们有任何疑问，继续向我提问。此外，我还会告诉他们尤达的智慧之言：“传承你所学”，意思是当时机来临时，他们应该去指导自己的学员。我曾多次和我的前学员一起指导其他人，看到他们在指导过程中投入了同样的努力。
是不是让你感兴趣了？看看《FreeBSD 文档项目新人指南》。它向你展示了如何检出文档树以及如何对现有文档做出修改。快速入门部分涵盖了这些内容。如果你对手册页的修改感兴趣，它有专门的部分。其他部分涉及格式、格式元素以及如何正确配置你的编辑器，让你的工作更轻松。开始并不难，谁知道随着时间推移，这会引导你走向何方？
BENEDICT REUSCHLING 是 FreeBSD 项目的文档提交者，也是文档工程团队的成员。他还是 FreeBSD 基金会董事会的副主席。在过去，他曾在 FreeBSD 核心团队服务两届。他在德国达姆施塔特应用科技大学管理一个大数据集群。他还为本科生教授《开发者的 Unix》课程。与 Allan Jude 一起，他是每周 bsdnow.tv 播客的主持人。