Linux Foundation 项目

本页面包含“Google 文档季”接受的技术写作项目的详细信息。

项目摘要

开源组织：
Linux Foundation
技术文档工程师：
jaskiratsingh2000
项目名称：
CHAOSS：制作面向整个社区的 CHAOSS 手册
项目时长：
标准时长（3 个月）

Project description

项目摘要：

目前，CHAOSS 社区的各个工作组已经制定了自己的工作方式，并在不同的程度上记录了他们不同的流程。 工作组包括 Common Metrics WG、Diversity & Inclusion WG、Evolution、Risk 和 Value G Suite，这些工作组建立了自己的参与和工作方式，并调整了不同的沟通方式和工作文化。根据指标，这些工作组具有不同的关注领域和背景，适用于相应指标的小组领导了相应工作组类别下的各种研究和开发工作，并且知道主导相应类别下各种研究和开发的正确途径，但对于新人和现有贡献者而言，可能不知道如何参与或采取正确的工作方式。

正因如此，CHAOSS 社区里的内容没有得到标准化。因此，为了了解整个社区的工作文化的正确流程和基本基础，社区手册的目标是将关键信息集中到 CHAOSS 项目中，并对部分信息进行标准化。关键信息和标准化部分主要关注 CHAOSS 采用的流程，以便 CHAOSS 就社区如何完成工作达成一致意见，新人如何参与并遵循社区的基本方针，以及新人或现有成员在利用 CHAOSS 社区中发挥领导力时必须遵守的流程和路径。

该手册应是现有社区成员和新社区成员的指导手册，指导他们完成 CHAOSS 项目。该项目涉及一个用于收集和整理手册内容的创意部分，还有一个用来确定如何表现手册的技术部分。

您需要满足什么要求？

《社区手册》是一份文档，定义了社区的关键政策和规程，并概述了社区的使命、价值观和工作方式。

本手册清晰地介绍新加入的社区成员以及他们开展的工作。 目前，CHAOSS 社区手册位于 GitHub 存储库中，需要改进和重构，以提供面向新人和现有社区用户的更多信息。因此，这本 CHAOSS 社区手册将通过以下方式为新社区和现有社区成员提供帮助：

  • 规范并整理 CHAOSS 社区的政策，集中在一个地方
  • 传达社区的介绍、使命、愿景和领导力
  • 了解 CHAOSS 社区实践
  • 贡献准则
  • 定义项目工作流
  • 概述 CHAOSS 社区文化
  • 一般常见问题解答
  • 指导

项目说明：

社区手册分为多个“版块”，其中包含针对特定主题的适当详细信息。这些部分可分为以下几部分：

  • 简介
  • CHAOSS 社区创作方式
  • 领导之路
  • 术语
  • 贡献准则
    • 开发者
    • Designer（设计师）
    • Writer
    • 营销者
  • 指标
  • CHAOSScon
  • CHAOSScast
  • 会议视频
  • 常规常见问题解答
  • 指导
    • Google 编程之夏
    • 主动联系
    • Google 文档季

详细的项目可交付成果

1.) 简介：

此部分是 CHAOSS 社区手册的第一页，其中涵盖了该手册的详细信息、概述和用法。以下内容如下：

A.) 其中包含了欢迎辞，并对 CHAOSS 社区进行了简要的说明，帮助说服读者通读手册。我还将添加从 https://chaoss.community/chaoss-photo-album/ 获取的图片拼贴图，其中重点介绍了该社区的各种运动。 B.) 该网页还会包含所有部分的详细信息，其中有一行说明，用于解释每个部分，并提供适当的链接。 C.) 手册用法：手册用法：此处已提供手册用法 ( shorturl.at/cqQU6 )，但我将改进并重构现有手册用法，并采用更优的 Markdown 方法，其中将包括手册流（我还会说明当用户想要添加、删除或讨论与手册相关的内容时会发生什么情况）。它可能会跟进沟通流程，以处理与手册相关的任何事项。）手册指南（包括其在社区和范围内的使用）、对手册的贡献（包括人们应如何使用仓库以进行更改、更改 PR、更改手册和风格指南时要遵循的模板）以及分享关于手册的反馈。在“分享反馈”部分，我会提供一个模板以及可供用户后续跟进以提供或使用 GitLab 问题来接收反馈的不同方式。

2.) CHAOSS 社区的方式：

CHAOSS 社区模式对于人们了解社区实践和准则至关重要。Workflows 可以进一步强调该机制，并以最佳方式概述社区实践。此部分包括以下内容：

A.) 一般价值：概述在 CHAOSS 社区中如何处理可持续性、开放性和透明度。我会解释这些价值观，说明新用户或现有用户应如何理解这些价值观，并在与社区开展合作时加以考虑。 B.) 社区准则：包括用户实际应如何参与 CHAOSS 社区并遵守一些基本条款。这也会解释社区内部所遵循的工作文化。（正确做法和错误做法）。其中包括核心贡献者/维护者核对清单，并让他们了解自己应该如何与维护人员合作，以及他们的核对清单是什么。 C.) 工作组：此页面( https://chaoss.community/participate/ ) 包含工作组的相关信息，例如工作组说明、代码库链接和会议信息，但在手册中，我会说明如何参与不同的工作组、了解评估各项指标的流程、了解各个 WG 的工作文化，以及如何成为不同工作组的核心贡献者。

3.) 领导之路：

不过，在开源项目中获得领导对于社区自身在商业领域取得成功至关重要。因此，考虑到这一点，我将添加以下内容：

A.) 技术领导层：其中包括 Repo 维护人员、文档编写者和网站维护者的流程和职责 B.)管理领导层：其中包括董事会成员和决策者 C. 的途径。运营领导层：此课程将包含社区管理者的学习路线

4.) 术语：

术语有助于描述 CHAOSS 社区中使用的术语和相关资产。此外，我还会附上术语使用准则，例如大写、缩写和应避免使用的字词，并说明原因。 将涉及的条款包括：CHAOSS 项目、开源社区健康、代码审核、工作组、开源软件指标、通用指标、多样性和包容性指标、演变工作组、风险工作组、价值工作组、指标发布和关注领域。

5.) 贡献准则：

这是所有开源社区的主要背景，因为大多数开源社区都依赖于所做的贡献或志愿服务工作，因此这将有助于加入社区的所有新手/用户了解他们必须遵守的基本必要性和准则。因此，其中包括以下详细信息：

A.) 了解社区路线图：此主题将简要介绍 CHAOSS 社区的路线图，这可以帮助用户知道应该以哪种方式或流程为 CHAOSS 项目中的各种工作确定优先事项。 B.) 说明在实际工作中做出任何贡献（例如开发、编写文档、设计、测试等）所需的必要内容 C.简要介绍 GitLab 的工作原理 D.）审核者/维护者指南

本部分还包含“贡献”类别对应的“角色和职责”，如下所示：

a.) 设计：该小节包括“CHAOSS 设计工作流程”和“设计准则”，其中包括设计原则、流程和所使用的工具，贡献者在为设计领域做贡献时必须遵守这些原则。 b.)DEVELOPMENT：包含对代码库的贡献的指南。其中包括技术要求、项目结构、项目设置（Augur、Cregit、GremoireLab） c.)文稿：其中包括相关文档资源，包括工具和风格指南。 d.)主动联系：这将包括贡献者如何为 CHAOSS 社区提供支持，推动他们发展 - 撰写博客、使用社交媒体用户名、组织聚会和活动

6.) 指标

目前，CHAOSS 社区网站包含 Metric Releases( https://chaoss.community/metrics/ ) 的信息，更让人们了解如何按照流程在该网站上提供其指标网站。因此，本部分将提供相关信息，帮助用户了解指标发布流程和运作方式。

7.）CHAOSScon：

GitHub( https://github.com/chaoss/governance/blob/master/community-handbook/chaosscon.md) 和网站( https://chaoss.community/CHAOSScon-2020-NA/ ) 上已有关于 CHAOSScon 的信息，但最好在手册中添加关于 CHAOSScon 流程和管理方式的详细信息和信息。手册中将包含以下信息：

A.) 有关组委会的详细信息：其中解释了加入 CHAOSScon B 组委会的过程。）提案请求管理流程：具体包括管理作者注册、提交提案和文档、审核和审批流程。 C.) CHAOSScon 计划的管理和发布 D.）如何管理广告和营销资料 E.)如何处理包天提案和赞助（包括资源包）

8.）CHAOSScast：

CHAOSScast 信息位于 https://github.com/chaoss/governance/blob/master/community-handbook/chaosscast.md 中，将包含在手册中，并提供一些额外的详细信息，例如参与情况、组织委员会、广告和营销材料。

9.）会议视频：

它将包含过去的所有会议视频以及 YouTube 上提供的其他说明，如参加者、日程等。

10.）一般常见问题解答：

其中将包含社区内经常提出的常见问题，这将有助于新社区成员和现有社区成员回答其中的部分问题。

11.）Google 编程之夏：

此部分将包含 Google 编程之夏、资格标准以及有关人们如何参与 Google 编程之夏 CHAOSS 社区的信息。此部分还将包含提案模板，人们可用它来起草提案以及角色和职责。 此外，本演示文稿还将包含相关信息，帮助现有社区成员了解成为组织管理员和导师的流程。

  1. 主动联系：

本部分包含有关主动联系的信息、资格标准，以及有关人员如何参与 Outreachy 的 CHAOSS 社区的信息。此部分将说明角色和职责，包括成为组织管理员和导师的过程。

  1. Google 文档季：

本部分将包含有关 GSoD 的信息、资格要求，以及有关参与者如何参与 GSoD CHAOSS 社区的信息。其中将说明各个角色和职责，包括成为组织管理员和导师的过程。

项目预期结果：

手册在任何社区中都发挥着重要作用。同样，这本 CHAOSS 社区手册也有助于为 CHAOSS 社区编写更条理、更详细的文档。任何加入社区的新人以及社区内的现有成员都能很轻松地了解 CHAOSS 社区的基础和工作方式。 此外，本手册还将为 CHAOSS 社区提供通向不同工作文化的各种流程和途径。

技术详情：

我提议使用 Gitbook 平台维护手册，因为这是一个方便用户使用的协作式项目，可帮助团队更加高效地工作。 GitBook Platform 的部分功能：

  • 所见即所得：强大而美观的文本编辑器
  • Markdown：对 Markdown 快捷方式的强大且富有成效的支持
  • 富媒体嵌入：可嵌入外部网络内容，如视频、代码段、文章、音乐等
  • 面向作者的信息中心：为作者打造智能信息中心，支持直观编辑
  • 草稿：草拟新更改并异步协作
  • 支持评论：讨论和审核草稿更改
  • 曲目写入记录：记录所有内容。查看并还原更改
  • 数据分析：它还支持跟踪流量、评分和内容质量的数据分析
  • GitHub 同步：保留工作流并将文档与 GitHub 同步
  • 自定义 品牌：自定义域、自定义徽标、字体、颜色、主题、标题等

以下这些图片可让您大致了解该平台

  • shorturl.at/GNQR4
  • shorturl.at/gATZ8
  • shorturl.at/qrE57
  • shorturl.at/rFRX6
  • shorturl.at/eyLW1
  • shorturl.at/rwHS8

-- 手册将在何处托管？

手册将托管在 GitBook 上，GitHub 为自定义网域、常见错误和搜索引擎优化 (SEO) 提供了适当的机制。

自定义网域： 如果 CHAOSS 社区希望将其托管在自定义网域上，则其显示方式如下：docs.chaoss.community。组织只需要构建他们希望拥有的任何子网域。要设置组织网域，请在 Gitbook Platform 上前往相应组织的设置。 图片示例：shorturl.at/GNQR4

GitBook 聊天室通过我们自己的 CDN 提供，默认启用 HTTPS。证书由 LetsEncrypt 颁发

支持的网域：

  • 子网域：www.example.com
  • 自定义网域：docs.example.com

- 如何将 Gitbook 与 GitHub 同步，以便在这两个平台上有效完成修改？

与 GitHub 的集成非常易于使用：如果有人更改 GitBook 上的某些内容，他们所做的修改会推送到 GitHub 代码库。相反，推送到 GitHub 代码库的提交内容会导入到 GitBook 中。

设置 GitHub 集成：

  • 在您的 GitBook 平台中，依次点击“Integration”（集成）标签页 > GitHub
  • 授权 GitBook 访问与贵组织关联的 GitHub 账号
  • 转到您的组织的 GitHub 并为“HandBook”创建一个代码库，例如 chaoss-handbook
  • 现在，在 GitBook 平台内的授权选项中选择要连接的名为 chaoss-handbook 的代码库。

完成这些步骤后，GitBook 会向 chaoss-handbook 代码库添加一个 webhook，以便随时获取对代码库进行的每项更改的内容。更改 GitBook 时，系统会推送新评论。

这样就搞定啦！任何人都可以通过 GitBook 或 GitHub 代码库继续编辑。

- 如何在 GitBook 平台上编辑页面？

任何想要修改 GitBook 平台中任何内容的人都必须通过邀请或加入链接加入 GitBook 平台。GitBook 支持视觉编辑，用户可以直接在页面中撰写内容。

草稿是用户内容的可编辑版本，只有作者可以访问。草稿会在您开始撰写内容（编辑器中的第一个字母、创建新页面、上传图片等）后自动创建。

对草稿做出的更改是正确的，这可让用户与其他成员同时对同一文档进行编辑，而不会产生任何冲突！这就是我们所谓的异步编辑和解决冲突。

草稿的第一个版本并非总能立即发布。如果您想以后再继续工作，或者您的内容尚未准备好进行“合并”，可以使用“保存”功能。

完成编辑后，您可以“合并”草稿。之后，您的团队成员便可看到您撰写的内容或您所做的更改，并且/或者会公开显示。

图片示例：shorturl.at/gATZ8 和 shorturl.at/qrE57

-- 内容结构：

目录：每个空间可以包含任意多个页面，以根据需要撰写文档。所有这些页面都显示在屏幕左侧的“目录”中。在目录中，您可以管理页面：创建新页面、页面组、添加外部链接、添加变体、导入外部文档（例如 Markdown（.md 或 .markdown）、HTML (.html)、Microsoft Word (.docx) 等外部文档。

初始页：初始页是文档的首页或根目录，基本上是文档中所有页面的母版。由于此页面是您的文档和空间的主要入口，您无法移动、删除此页面、拥有子页面或位于群组下。

页面：一个页面在编辑器顶部显示标题，可选说明。然后，您就可以撰写任意类型的内容并向其中添加内容。您可以将页面拖放到页面下方，从而实现页面嵌套。网页的子项将隐藏，但可以收起。

外部链接：这些条目是外部链接，编辑器中没有任何内容。其主要功能是提供指向外部网站的链接。

变体：您可以通过创建变体来为文档创建替代内容。这对于记录 API、库或翻译的多个版本非常有用。

图片示例：shorturl.at/eyLW1 和 shorturl.at/rFRX6

-- 手册将如何在客户方展示？

Chaoss 社区手册可通过子网域 https://docs.chaoss.community 访问，在用户端将按照以下方式查看：

  • Mattermost 手册 - https://handbook.mattermost.com/
  • Linux 基础社区桥文档 - https://docs.linuxfoundation.org/docs/ 等等

项目时间表：

1.) 社区凝聚力阶段（8 月 17 日至 9 月 13 日）

A.) 第 1-4 周：

  • 与导师讨论项目
  • 研究和收集项目各个部分所需的信息，向社区提出澄清性问题
  • 向社区明确说明手册使用的平台（我建议使用 GitBook）并设置相应平台
  • 协助解决文档问题

2.) 文档制作阶段（9 月 14 日至 11 月 30 日）

A.) 第 5 周（9 月 14 日至 9 月 20 日）

  • 草稿”简介部分

B.) 第 6 周（9 月 21 日 - 9 月 27 日）

  • 起草“CHAOSS 社区之路”版块

C.) 第 7 周（9 月 28 日 - 10 月 4 日）

  • 起草“成为领导之路”版块
  • 起草“术语”部分

D.) 第 8 周（10 月 5 日 - 10 月 11 日）

  • 起草社区路线图
  • 设计贡献指南草稿

E.) 第 9 周（10 月 12 日 - 10 月 18 日）

  • “草稿开发”部分

F.) 第 10 周（10 月 19 日至 10 月 25 日）

  • “写作和主动联系”部分指南

G.) 第 11 周（10 月 26 日 - 11 月 1 日）

  • “草稿指标”部分
  • CHAOSScon 草稿部分

H.) 第 12 周（11 月 2 日 - 11 月 8 日）

  • 设计会议版块

  • 起草社区一般常见问题解答

    I.) 第 13 周（11 月 9 日 - 11 月 15 日）

  • GSoC 指南草稿

J.) 第 14 周（11 月 16 日 - 11 月 22 日）

  • 主动联系指南草稿

K.) 第 15 周（11 月 23 日 - 11 月 29 日）

  • 缓冲时间；美化和改进整篇文档

3.) 评估阶段（11 月 30 日至 12 月 5 日）

A.) 第 16 周：

  • 起草项目报告
  • 填写项目的评估

社区互动

1.) 与社区参与和讨论。

我从 2020 年 4 月就在 CHAOSS 社区中四处探索，还与社区成员和我的特定项目导师（Georg Link 和 Armstrong Foundjem）进行了各种讨论。例如，“提出将 Gitbook 作为托管社区手册的平台”这一主题引起了社区成员的兴趣，您可以在 CHAOSS 归档邮寄名单会话中找到名为“Proposing Gitbook as a platform for Hosting”（社区手册）的平台。我还参加了社区每周通话，这帮助我向社区提供了最新动态。

2.) 您将如何收集该项目所需的信息？

由于这个项目需要制作整个社区手册，因此我们将从社区成员那里收集必须访问的信息并与社区成员进行讨论。正如我在上面拟定的时间安排，根据我的时间安排，我能够讨论并收集在与社区建立情感联系期间所需的信息。

我会按照 CHAOSS 对各个部分进行研究，并及时跟进邮件列表。我会试着根据具体要求向导师和社区提出澄清性问题。

为了简要讨论一下这个问题，我还会参加每周的通话。

3.) 您打算如何让社区了解您的进度，以及在项目过程中可能遇到的任何问题或疑问？

为保证灵活度和透明度，我会试着通过邮寄名单讨论来询问我的疑问。

我会通过博文分享我的每周进度，其中包括 scrum 文档和面临的挑战，这些内容将通过社区邮寄名单进行分享，以便吸引开源组织内的更多受众。

我还会参加每周的社区通话，以便就主要问题获得适当的建议和讨论。

我还打算创建一个 Trello 图板，其中包含每周可以完成的任务。然后，导师可以使用此面板清晰简明地了解当前的问题和功能。

4.) 如果你在项目过程中遇到困难，并且导师不在身边，你会怎么做？

我认为导师的职责是引导学生朝着正确的方向前进，而不是向学生解释每一个循环。项目的研究和实施是学生全权负责。记住，我只有在万不得已时，才会尝试向导师寻求帮助。

但是，如果导师在我需要帮助期间不在您身边/我很忙，我接下来会在 CHAOSS 社区中分享我遇到的问题。我确信有人能帮助我解决我遇到的任何难题。我还会在 dev.to 等在线论坛/开发者社区中分享问题

此外，我会试着在 CHAOSS 社区内参加每周一次的通话，以寻求我的疑惑。