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