格罗金医生

作者: 艾米·乌卡西克(Aimee Ukasick),独立贡献者

grok:深刻而直观地理解

定义由Merriam Webster在线词典提供

简介-新的SIG文档贡献者的观察

我于2019年8月开始为SIG Docs社区做出贡献。有时,我感到 就像我是在陌生地区适应新社区的陌生人一样: 调查社区组织,了解贡献者社会, 学习新课程,并加入新的行话。我既是观察员,也是 contributor.

观察01:阅读 有助于 页!

我向OpenStack,OPNFV和Acumos贡献了代码和文档,所以我 认为为Kubernetes文档做出贡献将是相同的。我曾是 错误。我应该彻底 为Kubernetes做贡献 docs 页面而不是浏览页面。

我对git / gerrit工作流程非常熟悉。使用这些工具,贡献者可以克隆 the master repo 和 的n creates a local branch. Kubernetes uses a different approach, called 叉和拉. Each contributor forks 的 master repo, 和 然后贡献者在创建请求请求之前将工作推送到他们的fork。一世 按照的说明创建了一个简单的拉取请求(PR) 开始 contributing 页面的 提交拉 request 部分。本节介绍如何使用 GitHub UI。我了解到,此方法适合需要更改 一次提交修复。但是,当您必须 对您的PR进行其他更新。 GitHub为每次更改创建一个新提交 使用GitHub UI制作。 Kubernetes GitHub组织需要压缩提交。 The 开始贡献 页面没有提到挤压提交,所以我看着 GitHub和git文档。我无法使用GitHub压缩提交内容 UI. I had to git fetchgit checkout my pull 请求 locally, squash 的 使用命令行提交,然后推送我的更改。如果 开始 contributing 提到过挤压提交,我本可以在当地工作 复制而不是使用GitHub UI。

观察02:伸出援助手

在进行我的第一个PR时,我对在本地克隆中工作有疑问 and about keeping my fork updated from upstream master. I turned to searching 互联网而不是询问 Kubernetes松弛 #sig-docs 渠道. I used 的 wrong process to update my fork, so I had to git rebase my PRs, which did not go well at 所有. As a result, I closed those PRs 并提交了新的。当我在#sig-docs频道上寻求帮助时, 贡献者发布了有用的链接,我的本地git配置文件应该看起来像什么 ,以及要运行的git命令的确切集合。贡献者使用的过程 与定义中的定义不同 中级贡献 页。 如果我问什么GitHub工作流程来节省我很多时间, 采用。记录的社区知识越多,新知识就越容易 贡献者可以迅速提高生产力。

观察03:不要让冲突的信息毁了你的一天

Kubernetes社区有一个针对以下内容的贡献者指南 还有一个 文件资料。的 指南中包含有关同一主题的冲突信息。例如,SIG Docs GitHub流程建议根据以下内容创建本地分支 upstream/master。的 Kubernetes社区贡献者 Guide 提倡从上游更新您的fork,然后创建本地分支 根据你的叉子。新的贡献者应该遵循哪个过程?是两个 流程可以互换吗?提出有关冲突的最佳地点 信息是#sig-docs或#sig-contribex渠道。我要求 #sig-contribex频道中有关GitHub工作流程的说明。 @cblecker提供了非常详细的回复,我使用它来更新 中级贡献 页。

观察04:信息可能分散

大型开放源代码项目通常在各处散布信息 各种回购或在回购之间重复。有时小组会各自为政, 信息不共享。其他时候,一个人去上班 不同的项目而无需传递专业知识。 存在文档空白,并且由于更高的优先级而可能永远无法纠正 项目。因此,新的贡献者可能很难找到基本信息,例如 as meeting details.

参加SIG Docs会议是参与其中的好方法。但是,人们 很难找到会议URL。大多数新的贡献者在 #sig-docs频道,但我决定在docs中找到会议信息。 这需要在多个页面上单击几下。有多少新贡献者错过了 会议,因为他们找不到会议详细信息?

观察05:忍耐是一种美德

贡献者可能需要等待几天才能收到有关较大PR的反馈。过程从 提交最终批准可能需要数周而不是数天。那里有两个 原因如下:1)大多数审稿人兼职从事SIG Docs;和2)评论者 想要提供有意义的评论。 SIG中不会发生“开车兜风审查” 文件!审阅者检查以下内容:

  • 提交消息和PR描述是否充分描述了更改?

  • PR是否遵循样式和内容指南中的指南?

    • 总体而言,语法和标点符号正确吗?
    • 内容是否清晰,简洁且适合非母语人士?
    • 内容在样式上是否适合其余文档?
    • 内容的流向有意义吗?
    • 是否可以进行任何更改以使内容更好,例如使用Hugo简码?
    • 内容渲染正确吗?
  • 内容在技术上是否正确?

有时,审核过程使我感到防御,烦恼和沮丧。我是 确保其他贡献者也有同样的感觉。贡献者需要耐心! 编写出色的文档是一个反复的过程。审稿人仔细检查 公关,因为他们希望保持文档的高质量, 不是因为他们想惹恼贡献者!

观察06:使每个单词都计数

非英语母语者阅读并为Kubernetes文档做出贡献。 在编写内容时,请使用简洁明了的简洁语言 句子。您写的每个句子都可能被翻译成另一种语言,因此 删除不添加实质内容的单词。我承认实施这些 指导有时具有挑战性。

问题和请求请求不会翻译成其他语言。但是你 在撰写说明时,仍应遵循上述准则 对于问题或请求请求。您应该添加详细信息和背景 有关问题的信息,因此进行分类的人不必应用 triage/needs-information 标签。同样,创建拉取请求时, 应该添加有关审阅者没有的内容更改的足够信息 找出请求请求的原因。清楚地提供细节, 简洁的语言可以加快流程。

观察07:对问题进行分类比应做的困难

在SIG文档中,分类问题需要能够区分 支持,错误和功能要求,不仅针对文档,还针对 Kubernetes代码项目。如何路由,标记问题并确定优先级已成为 每周都更轻松。我仍不清楚100%是哪个SIG和/或项目 负责文档的哪些部分。 SIG和工作组 帮助, 但这还不够。在文档中的页面级别,它不是 始终清楚哪个SIG或项目具有领域专业知识。页面的正面 有时有时会列出审阅者,但从未列出SIG或项目。每页应 指出谁负责内容,以便SIG Docs分类人员知道在哪里 route issues.

观察08:SIG Docs人手不足

文档是软件采用的首要驱动力1.

许多贡献者花了很少的时间来研究SIG文档,但是只有很少的时间 是训练有素的技术作家。很少有公司雇用技术作家来从事 Kubernetes文档至少有一半时间。这对于在线来说非常令人沮丧 229个文档中来自读者的唯一页面浏览量超过5300万 国家/地区截至2019年。

SIG Docs由于缺乏技术编写者而面临挑战:

  • 在Kubernetes文档中保持高质量: 有超过750页的文档。那是 750页 检查 定期过时的内容。这不仅仅是运行链接 checker against 的 kubernetes/website repo. This involves people having a 对Kubernetes的技术了解,了解哪些代码版本发生了变化 影响文档,并知道内容在 文档,以便 所有 受影响的页面和示例代码文件已更新 及时地。其他SIG对此有所帮助,但基于 读者提出的问题,没有足够的人致力于保留内容 fresh.
  • 减少审查和合并PR的时间: The larger 的 size of 的 PR, 的 longer it takes to get 的 lgtm label and eventual approval. My size/M 和 larger PRs took from five to thirty 批准的天数。有时我会礼貌地请审稿人在以后再次审阅 我已推送更新。有时我在#sig-docs频道上要求 任何 approver 看看并批准。人们很忙。人们继续 假期。人们还会继续担任不涉及SIG Docs和 忘记从审阅者和批准者分配文件中删除自己。 合并时间的很大一部分原因是没有足够的审阅者, 批准者。另一部分是 高 barrier 成为审阅者或批准者,比我在其他地方看到的要高得多 开源项目。经验丰富的开源技术作家,他们希望 对SIG文档的贡献并未迅速进入批准者和审阅者角色。 一方面,高壁垒确保了那些角色被人们填补 至少具有Kubernetes文档知识水平;在另一 一方面,这可能会阻止经验丰富的技术作家完全贡献自己的力量,或者 来自分配技术作家到SIG Docs的公司。也许SIG文件应该 考虑通过降低Kubernetes社区要求 在个别情况下成为审核者或批准者的障碍 course.
  • 确保所有页面的命名一致: 术语应与 标准化词汇。保持一致可以减少混乱。 跟踪并解决这些问题很耗时,但对读者来说值得。
  • 与指导委员会合作制定项目文档指南: The Kubernetes存储库准则 根本不提文档。之间 该项目的GitHub文档和Kubernetes文档,有些项目几乎 内容重复,而其他内容冲突。创建清晰 指导方针,使项目知道要制定路线图,里程碑和全面 feature details in 的 kubernetes/<project> repo 和 to put installation, Kubernetes文档中的配置,用法详细信息和教程。
  • 删除重复的内容: Kubernetes用户安装Docker,因此重复内容的一个很好的例子是 Docker安装说明。而不是重复Docker中的内容 文档,说明哪个版本的Docker与哪个版本的Kubernetes一起使用 并链接到Docker文档进行安装。然后详细说明 Kubernetes特定的配置。这个想法对于容器是一样的 Kubernetes支持的运行时
  • 删除第三方供应商内容: 这与删除重复内容紧密相关。一些第三方 内容由详细介绍外部产品的列表或表格组成。其他 第三方内容位于 任务讲解 部分。 SIG Docs不应该负责验证第三方产品 使用最新版本的Kubernetes。 SIG文档也不应 负责维护培训课程或云提供商的列表。 此外,Kubernetes文档不是向供应商推销的地方 产品。如果SIG Docs被迫撤销其不允许的政策 第三方内容,可能会引起 面向供应商或商业的请求请求。维护内容 给SIG文档增加了不必要的负担。
  • 指出每个任务和教程适用的Kubernetes版本: 这意味着查看每个发行版的每个任务和教程。读者群 假设任务或教程是最新版本的文档,则可以正常工作 使用最新版本的Kubernetes。
  • 解决问题: There 是 470 open issues in 的 kubernetes/website repo. It's hard to keep up with 所有 的 issues that 是 created. We encourage 那些提出较简单的问题来提交PR的人:大多数没有。
  • 创建更详细的内容: Readers 已指示 他们希望看到该网站所有部分的更详细的内容 文档,包括教程。

自2015年首次发布以来,Kubernetes取得了空前的增长。 任何快速发展的项目,都会有越来越大的痛苦。持续提供 高质量的文档是其中之一,而且非常重要 到一个开源项目。 SIG Docs需要一支更大的技术作家核心团队 被分配至少50%。 SIG Docs可以更好地实现目标,向前迈进 使用新内容,更新现有内容并及时解决未解决的问题。

意见09:平均来说,为技术文档项目做贡献比开发软件需要更多的技能

当我对我的前同事说时,反应是健康的 怀疑和许多笑声。似乎许多开发人员以及 经理,不完全了解哪些技术作家为开源做出了贡献 项目实际上是这样做的。完成了开发和技术写作 在22年的大部分时间里,我注意到技术作家的价值远低于 具有相对地位的软件开发人员。

SIG Docs核心团队成员所做的不只是根据要求编写内容:

  • 我们使用与开发人员相同的流程和工具,例如 终端,git工作流,GitHub和Atom,Golang和Visual Studio Code等IDE;我们 还使用特定于文档的插件和工具。
  • 我们注重细节以及设计和组织:全局 小图片。
  • 我们提供具有逻辑流程的文档;它不仅仅是页面上的内容 但网页适合各部分的方式以及各部分适合整体结构的方式。
  • 我们编写内容全面并且使用不懂英语的读者可以理解的语言。
  • 我们对使用各种标记语言的英语作文有把握。
  • 我们是技术人员,有时甚至达到Kubernetes管理员的水平。
  • 我们阅读,理解并偶尔编写代码。
  • 我们是项目经理,能够计划新工作以及为发布分配问题。
  • 我们是教育者和外交官,对我们进行的每一次审查以及对问题的任何评论都对我们有帮助。
  • 我们使用站点分析根据读者最常访问的页面以及读者认为无用的页面来计划工作。
  • 我们是测量师,定期征求社区反馈。
  • 我们对文档进行整体分析,确定应保留哪些内容, 根据可用资源和读者需求应删除哪些内容。
  • 我们对Hugo和其他用于 在线文档;我们知道如何创建,使用和调试Hugo短代码, 使内容比纯Markdown更健壮。
  • 我们不仅解决Hugo的性能问题,还解决Netlify的性能问题。
  • 我们解决了API文档的复杂问题。
  • 我们致力于提供我们可以提供的最高质量的文档。

如果您对Kubernetes文档的复杂性有任何疑问 项目,观看SIG Docs主席Zach Corleissen的演讲:

另外, Docs作为代码:缺少手册 (Jennifer Rondeau,Margaret Eker; 2016)是关于 一般而言,文档项目的复杂性。

编写文档 网站的YouTube channel 是 深入探讨技术写作的好,坏和丑陋的绝妙地方。

想想如果没有才华横溢的专业技术作家,开源项目将是什么!

观察十:社区就是一切

SIG Docs社区以及更大的Kubernetes社区都是敬业的, 聪明,友善,有才华,有趣,乐于助人以及其他 正面形容词!人们张开双臂欢迎我,不仅是因为SIG Docs需要更多的技术作家。我从来没有觉得我的想法和贡献是 被解雇,因为我是新手。谦虚和尊重很长的路要走。 社区成员拥有丰富的知识可以共享。参加会议,询问 问题,提出改进建议,感谢他人并做出贡献 尽你所能!

向在我期间帮助我并忍受我(LOL)的人们大声喊叫 闯入期:@ zacharaysarah,@ sftim,@ kbhawkey,@ jaypipes,@ jrondeau, @ jmangel,@ bradtopol,@ cody_clark,@ 的crudge,@ jaredb,@ tengqm,@ steveperry-53, @ mrbobbytables,@ cblecker和@ kbarnard10。

奥托罗

我是否看过SIG文档?还没有,但是我确实知道SIG文档需要更多 专用资源,继续取得成功。

引文

1 @linuxfoundation。 “ Google @megansanicki,开放源代码策略师Megan Byrd-Sanicki,文档是软件采用的第一推动力。#ossummit。” 推特,2019年10月29日上午3:54,twitter.com / linuxfoundation / status / 1189103201439637510。