本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- moja 全球
- 技术文档工程师：
- Tlazypanda（太空熊猫）
- 项目名称：
- FLINT 技术新手入门指南的文档
- 项目时长：
- 标准时长（3 个月）
Project description
FLINT 技术新手入门指南文档，用于指导新贡献者完成技术入门流程，以便新贡献者能够在维护人员的最低支持下轻松上手。
项目问题
下面列出了与当前文档相关的最严重问题： - 本地设置指南说明条理分明，使新贡献者难以上手。 - FLINT 的多个代码库缺少有关其用途的文档，并且之间互不关联，这使得新用户很难确定要安装哪个代码库。 - Windows 安装有详细的文档记录，但基于 Linux 的安装文档有改进空间。 - Git 工作流目前尚未纳入文档
建议的解决方案
此方案提出了一种解决方案，用于指导新贡献者完成技术新手入门，以便新的贡献者能够以维护者的最低支持轻松上手。为此，您可以重构当前文档，使其适合新手使用，同时又维护一个集中式独立仓库，用于存储所有可用文档。该项目分为三个阶段：- - 审核现有文档和重构：本阶段的目标是回顾当前指南，并对其进行重构，使其更易于新贡献者理解。此外，我们还需要修改本文档，为初学者提供更方便阅读的内容。为此，我们添加了一些标记、表情符号和有关问题相关信息，标记有“仅限初学者”或“良好的第一个问题”标签。 - 创建一个中央独立文档库：此阶段的目标是按照逻辑顺序在独立仓库中链接所有可用的文档。这包括订购贡献准则、项目设置说明和分步指南。- 为新开发者添加开发者工作流和社区网站：本阶段的目标是添加开发者工作流，其中包含 Git 贡献准则和项目的技术架构，以及测试和 QA 准则。提议的社区网站是一个单页应用，用于显示工作流程、新贡献者可以声明的首次问题以及所有贡献者的列表。 第 1 阶段：查看现有文档和重构：
修改以下代码库的当前文档： - FLINT：当前文档不是很详细，并且没有按顺序排列必需的必备库。分步指导指南分为不同的 PDF 文件，但可以在一个位置统一以更简洁的方式进行。此外，安装指南适用于 Windows，但对于 Linux 安装，重定向到 FLINT.docker 代码库可能有所帮助。 - FLINT.docker：当前文档并未提供设置此仓库的幕后目的，那就是通过 Docker 提供在 Linux 上安装的 FLINT。通过 Docker 提供的支持仅限于 Ubuntu 18.04 (Bionic Beaver)，但可以扩展到其他基于 Linux 的发行版。当前文档还需要着重介绍设置 dockerfile 的顺序方式，并提供有关如何从 makefile 进行构建的足够信息。 - FLINT.example：当前文档并未说明设置此仓库的幕后目的，而是提供了一个示例来说明如何使用 FLINT。不同的示例运行可以按照具体的运行说明更好地分离。我们还需要将此代码库链接到 FLINT 主代码库，为用户提供一种导航此处的方法，以便查看实际中的示例。
需要将以下信息添加到当前文档中： - Git 和 GitHub 用法：这将包含有关如何创建代码库分支、克隆以及设置远程上游代码库的分步说明。此外，本文档还介绍了如何针对最新的主实例执行 rebase 操作，以及如何处理合并冲突。 - 徽章和表情符号：当前文档缺少徽章和表情符号，这有助于新贡献者感觉自己受到欢迎，并发现不那么令人望而却步的问题。 - 关于入门/新手友好问题的信息：这有助于引导新贡献者解决对新手友好的问题和社区网站。 - Import-me 代码库的相关信息：Import-me 代码库充当快速启动任何 Moja 全局代码库的基准模板。当前文档没有提及这方面的重要性。它需要更新以提及“Import-me”代码库，并且还需要添加选择此代码库作为创建新代码库的模板的步骤。此外，还应建立一个既定的流程，以便编码器为 Import-me 代码库提供其他功能建议。
第 2 阶段：创建中央独立文档库：
用于托管平台的工具：
我们推荐这个托管平台使用“Read The Docs”，原因如下：- - 在不同托管平台中排名很高。 - 推送提交时自动更新 - 由于有大量社区在使用，因此易于设置和问题排查支持 - 文档使用 reStructuredText 设置格式，输出由 Sphinx 编译。
按逻辑顺序组织所有内容：
提议的内容顺序如下：- - 开发者文档简介：本部分将介绍 Moja Global 和 FLINT。 - 贡献：此部分将包括“贡献方式”（涉及代码/报告 bug/翻译/文档/组织活动等）和“行为准则”子部分。 - 开发设置：此部分将包括“Git 和 GitHub 工作流”“Windows 安装”“关于手动测试的下一个“Linux 工作流安装”和“Linux 工作流的下一个测试阶段”的子部分，这些子部分将包括以下内容：- 加入我们：此部分将提供各种社交论坛（例如 Slack 频道），以便您与 Moja Global 保持联系和开展合作。
第 3 阶段：为新贡献者添加开发者工作流和社区网站：
开发者工作流程文档：
开发者工作流文档将包含以下小节：
- 使用的技术栈/架构以及代码中的各种模块：帮助新贡献者熟悉所实现的技术栈、代码库的各种库和模块的文档。
- 集成式测试和覆盖率工具：推出新的贡献者，以测试用于测试的 CI/CD 流水线工具、覆盖率聊天机器人，以及针对其代码运行自动质量检查。此外，还要让他们知道在测试失败时应向谁寻求帮助。
- 用于简化工作流程的聊天机器人，例如：Zulipbot：设计用于显示聊天机器人的内容模板和提供文档，以便用户了解聊天机器人，甚至可以通过贡献内容改进聊天机器人的配置。
- 手动测试和提交拉取请求：将提供的文档说明如何根据特定标准手动测试拉取请求，并在提交拉取请求时以屏幕截图/GIF 的形式上传结果。
- 贡献者需遵循的拉取请求审核准则：如何标记特定团队进行审核，以及向拉取请求添加标签（例如“需要审核”），以便维护人员进行回复。
社区网站：
社区网站将具有以下功能：-
- 有关我们工作流程的信息：该工作流程包括新贡献者可以首先执行的一系列操作，例如：声明第一个计时器问题，然后为其他人创建第一个计时器问题，并通过提供反馈和查看他们的拉取请求来帮助他人。
- 第一个计时器问题列表：专门面向新手或新贡献者的问题列表。
- “过时问题”列表：长期未处理的问题列表可供贡献者选择。
- 贡献者名单：迄今为止为 Moja Global 代码库做出贡献的贡献者名单。
- 近期贡献者：最近为 Moja Global 代码库做出贡献的贡献者名单。
- 加入聊天论坛的链接：用于加入 Slack 社区的信息和链接，以解决他们的问题并就项目进行进一步讨论。