本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- Linux 基金会
- 技术文档工程师：
- jaskiratsingh2000
- 项目名称：
- CHAOSS：创建 CHAOSS 社区手册
- 项目时长：
- 标准时长（3 个月）
Project description
项目摘要：
目前，CHAOSS 社区中的工作组已开发出自己的工作方式，并在不同程度上记录了各自不同的流程。工作组包括“通用指标”工作组、“多元化与包容性”工作组、“演变”“风险”和“价值”工作组，这些工作组各自制定了参与和工作方式，并适应了不同的沟通方式和工作文化。这些工作小组根据相关指标，有着不同的侧重点和背景，分别针对合适的指标负责开展各个工作组类别下的各种研究和开发工作，并且了解开展各个类别下各种研究和开发的正确途径，但对于新成员和现有贡献者，可能不知道如何参与或采用正确的途径来开展各自的工作。
因此，CHAOSS 社区中的内容并未标准化。因此，为了了解整个社区正确的工作流程和工作文化基本要素，社区手册的目标是集中收集关键信息，并在 CHAOSS 项目中对部分信息进行标准化。关键信息和标准化部分主要侧重于 CHAOSS 使用的流程，以便 CHAOSS 就社区如何完成工作、新手如何参与并遵循社区的基本原则以及新手或现有成员必须遵循哪些流程和途径来获得 CHAOSS 社区领导地位达成共识。
该手册应作为指南，指导现有和新社区成员如何在 CHAOSS 项目中完成工作。此项目涉及收集和整理手册内容的创意性部分，以及定义手册呈现方式的技术性部分。
有何需求？
社区手册是一项文档，用于定义社区的关键政策和程序，并概述社区的使命、价值观和运作方式。
本手册清晰地介绍了新加入社区的成员，并介绍了具体方法。 目前，CHAOSS 社区手册已在 GitHub 代码库中发布，但需要进行改进和重构，以便为新手和现有社区用户提供更多信息。因此，这本 CHAOSS 社区手册将通过以下方式帮助新手和现有社区成员：
- 对 CHAOSS 社区的政策进行形式化和整理，将所有政策集中到一个位置
- 传达社区的简介、使命、愿景和领导团队
- 了解 CHAOSS 社区做法
- 贡献准则
- 定义项目工作流
- 概述 CHAOSS 社区文化
- 一般常见问题解答
- 指导
项目说明：
社区手册将分为多个“部分”，其中包含与特定主题相关的适当详细信息。这些部分可以按以下方式划分：
- 简介
- CHAOSS 社区方式
- 通往领导之路
- 术语
- 贡献准则
- 开发者
- 设计师
- 写入者
- 营销者
- 指标
- CHAOSScon
- CHAOSScast
- 会议视频
- 常规常见问题解答
- 导师计划
- Google 编程之夏
- Outreachy
- Google 文档季
详细的项目交付成果
1.) 简介：
本部分将作为 CHAOSS 社区手册的第一页，将介绍手册的详细信息、概览和使用方式。具体内容如下：
A.) 其中包含欢迎辞以及对 CHAOSS 社区的简要说明，以帮助说服读者阅读手册。我还会添加一张图片拼接图，其中包含从此处 https://chaoss.community/chaoss-photo-album/ 获取的图片，以突出展示社区中的各种运动。 B.) 该页面还将包含有关所有部分的详细信息，其中包含一条说明每个部分的说明和适当的链接。 C.) 手册使用：此处已有手册使用（shorturl.at/cqQU6），但我将使用更好的 Markdown 重构和改进现有手册使用，其中将包括手册的流程（我将说明当用户想要添加、移除或讨论与手册相关的内容时会发生的情况。It might follow up the process of communication way for any handbook related things.), 手册指南（包括在社区中的使用和范围）、对手册的贡献（包括如何使用代码库进行更改、提交 PR、更改手册和样式指南时应遵循的模板），以及分享有关手册的反馈。在“分享反馈”中，我将添加一个模板，以及用户可以通过哪些方式跟进以提供反馈或使用 GitLab 问题来接收反馈。
2.) CHAOSS 社区方式：
CHAOSS 社区方式对于用户了解社区做法和准则至关重要。Workflows 会对其加以强调，并用最佳方式概述社区实践。本部分包含以下内容：
A.) 一般价值：概述 CHAOSS 社区如何处理可持续性、开放性和透明度。我将说明这些价值，以及新用户或现有用户在社区内工作时应如何理解和考虑这些价值。 B.) 社区准则：包括用户实际上应如何参与 CHAOSS 社区并遵守基本条款。这还会说明社区内遵循的工作文化。（正确做法和错误做法）。其中将包含核心贡献者/维护者核对清单，并让其他人了解他们应如何与维护者合作以及维护者核对清单。 C.) 工作组：此页面( https://chaoss.community/participate/ ) 包含有关工作组的信息，例如工作组说明、代码库链接和会议信息，但在本手册中，我将介绍如何参与不同的工作组，了解评估指标的过程、了解各个工作组的工作文化，以及如何成为不同工作组的核心贡献者。
3.) 领导之路：
虽然在开源项目中取得领导地位对社区在商业领域取得成功至关重要，因此，我会考虑以下事项：
A.) 技术领导层：包括 Repo 维护人员、Documentation Writer 和网站维护人员的相关流程及职责。 B.)治理领导：这将包括董事会成员和决策者的途径 C.) 运营领导：此部分将包含社区管理员的途径
4.) 术语：
术语有助于描述 CHAOSS 社区中经常使用的术语及其各自的属性。此外，我还会附上术语使用指南，例如大写形式、缩写和应避免使用的字词及其原因。 包含的术语包括 CHAOSS 项目、开源社区健康状况、代码审核、工作组、开源软件指标、常见指标、多元化和包容性指标、演化工作组、风险工作组、价值工作组、指标版本、重点领域。
5.) 贡献准则：
这是任何开源社区的主要背景，因为大多数开源社区都依赖于贡献或志愿者工作，因此这有助于加入社区的任何新手/用户了解他们必须遵循的基本必要性和准则。因此，其中将包含以下详细信息：
A.) 了解社区的路线图：本主题将简要介绍 CHAOSS 社区的路线图，这有助于用户了解应遵循哪种方式或流程来确定 CHAOSS 项目中的各种工作的优先级。 B.) 说明实际贡献任何内容（例如开发、文档编写、设计、测试等）所需的必要条件 C.) 简要了解 GitLab 的工作原理 D.)审核员/维护者指南
此部分还将包含每个贡献类别的“角色和责任”，如下所示：
a.) 设计：该小节将包括“混乱设计工作流程”和“设计指南”，其中包括设计原则、流程和使用的工具，贡献者在为设计领域做出贡献时必须遵循。 b.)开发：其中将包含有关向代码库贡献内容的指南。其中将包含技术要求、项目结构、项目设置（Augur、Cregit、GremoireLab） c.)文档：其中将包含文档资源，包括工具和样式指南。 d.) 宣传：包括贡献者如何支持 CHAOSS 社区在宣传方面实现增长 - 撰写博文、使用社交媒体标识名、组织 Meetup 和活动
6.) 指标
目前，CHAOSS 社区网站包含指标版本信息( 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 夏季编程活动、资格条件，以及 CHAOSS 社区成员如何参与 Google 夏季编程活动。此部分还将包含提案模板，供用户起草提案以及角色和职责。 此外，该页面还将包含有助于现有社区成员了解成为组织管理员和导师的流程的信息。
- Outreachy：
此部分将包含有关主动联系、资格条件的信息，以及有关人们如何在 Outreachy 中参与 CHAOSS 社区的信息。其中包含角色和职责，包括成为组织管理员和导师的流程。
- Google 文档季：
本部分将介绍 GSoD、资格条件，以及参与者如何在 CHAOSS 社区中参与 GSoD 的相关信息。其中包含角色和职责，包括成为组织管理员和导师的流程。
项目预期成果：
手册在任何社区中都发挥着重要作用。同样，这本 CHAOSS 社区手册将为 CHAOSS 社区提供更有条理、更详细的文档。这样一来，加入社区的任何新手以及社区中的现有成员都可以轻松了解 CHAOSS 社区的基础知识和运作方式。 此外，本手册还将介绍 CHAOSS 社区中不同工作文化的各种流程和途径。
技术详情：
我建议使用 Gitbook 平台来维护手册，因为它是一个简单易用的协作项目，可让团队更高效地工作。 GitBook 平台的一些功能：
- 所见即所得：功能强大且美观的文本编辑器
- 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 平台上的组织设置。 图片示例：shorturl.at/GNQR4
GitBook 聊天室通过我们自己的 CDN 提供，默认启用 HTTPS。证书由 LetsEncrypt 颁发
支持的网域：
- 子网域：www.example.com
- 自定义网域：docs.example.com
-- 如何将 Gitbook 与 GitHub 同步，以便在两个平台上都有效地进行编辑？
与 GitHub 的集成非常易于使用：如果任何人更改了 GitBook 上的内容，其所做的修改会推送到 GitHub 代码库。反之，推送到 GitHub 代码库的提交会导入到 GitBook 中。
设置 GitHub 集成：
- 在 GitBook 平台中，点击“Integrations”（集成）标签页 > GitHub。
- 授权 GitBook 访问与您的组织相关联的 GitHub 账号
- 前往贵组织的 GitHub 账号，为“手册”创建一个代码库，例如 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 Foundation Community Bridge 文档 - 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 日）
- “The CHAOSS Community Way”部分草稿
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 日）
- Outreachy 指南草稿
K.) 第 15 周（11 月 23 日至 11 月 29 日）
- 缓冲时间；对整个文档进行润色和改进
3.) 评估阶段（11 月 30 日至 12 月 5 日）
A.) 第 16 周：
- 起草项目报告
- 填写项目评估
社区互动
1.) 与社区的互动和讨论。
我从 2020 年 4 月开始浏览 CHAOSS 社区，并与社区成员和我的具体项目导师（Georg Link 和 Armstrong Foundjem）进行了各种讨论。其中一个引起社区成员更多兴趣的讨论是“提议将 Gitbook 作为托管社区手册的平台”，您可以在 CHAOSS 归档邮寄列表会话中找到该讨论，该会话的名称为“提议将 Gitbook 作为托管社区手册的平台”。我还参与社区每周的通话，帮助我向社区通报最新动态。
2.) 您将如何收集此项目所需的信息？
本项目要求建立社区手册，以便向社区成员收集并与其讨论其中需要访问的信息。我已在上方提出时间表，我将根据该时间表在社区互动期内讨论和收集所需信息。
我将根据 CHAOSS 研究各个部分，并继续在邮寄名单中跟进会话。根据要求，我会尝试向导师和社区提出澄清性问题。
为了简化讨论，我也会加入每周的通话。
3.) 您如何提议让社区随时获知您的进度以及您在项目过程中可能遇到的任何问题或疑问？
为了灵活透明，我会尝试通过邮寄名单讨论来提出疑问。
我会以博文的形式分享自己每周的进度，其中包括 Scrum 文档和面临的挑战，这些内容将分享到社区邮寄名单中，以便覆盖开源组织内更广泛的受众。
我还会每周参加一次社区通话，针对主要问题提出适当的建议和讨论。
我还打算创建一个 Trello 看板，在其中列出每周可执行的任务。然后，导师可以使用此面板来简洁明了地了解当前的问题和功能。
4.) 如果您在项目中遇到问题，而您的导师不在身边，您会怎么做？
我认为导师的角色是引导学生朝着正确的方向前进，而不是向学生解释每个循环细节。项目的研究和实施完全由学生负责。有鉴于此，我只会在万不得已时尝试向导师寻求帮助。
不过，如果导师在我需要帮助时不在/很忙，我会转而向 CHAOSS 社区分享我遇到的问题。我相信有人能帮助我解决我遇到的任何难题。我还会在 dev.to 等在线论坛/开发者社区分享此问题
此外，我会尝试参与每周在 CHAOSS 社区内寻求帮助的通话，以便提出自己的疑问。