本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- Electron
- 技术文档工程师：
- 雾金
- 项目名称：
- Electron 教程流程
- 项目时长：
- 标准时长（3 个月）
Project description
项目摘要
Electron 是使用 JavaScript、HTML 和 CSS 构建跨平台桌面应用的最热门工具之一。基于 Electron 构建的应用集合包含近 900 个条目，并且此列表会不断扩展。一些最热门的开发者工具（例如 Visual Studio Code、Atom、Postman、Slack、GitKraken）都是基于 Electron 构建的。
Electron 的受欢迎之处在于其简单的学习曲线和较低的入门门槛 - 任何了解 JavaScript、HTML 和 CSS 堆栈的人都可以构建自己的应用。整体增长率非常高，因此制作易于掌握和使用的教程和入门指南十分必要。
该项目的目标是为刚开始接触 Electron 框架的应用构建者提供信心，并为他们提供从头开始开发自己的 Electron 应用的一致且简化的工作体验。
项目问题
以下是与 Electron 教程文档相关的最重要的问题列表： 1. 应用开发步骤的起点不明确，并且介绍信息不直观 2. 与应用开发流程相关的信息散乱且冗余 “入门”指南说明零散，没有单一可靠来源
项目提案
根据项目目标以及上述问题，下面列出了建议的增强功能： 1. 更新现有指南。为了让新手能够顺利、一致地完成前期步骤，我们应更新以下文档，使其从简单到复杂逐步过渡： - 开发者环境 - 编写您的第一个 Electron 应用 - 向应用添加功能（创建摘要页） - 应用打包和分发 2. 重构文档目录。为了向新的开发者展示入门必要和可考虑采取的后续步骤，文档页面应同时对步骤进行直观和上下文的划分，以便让第一个应用尽快上线。重组还包括有关可能的后续步骤的指导。3. 整理和统一应用开发文档。所有功能都应提供一套统一的说明，说明如何安装/启用该功能、如何快速上手、如何在首次启动后使用该应用以及如何分发该应用。 4. 在文档中添加了 electron-api-demos 代码库。electron-api-demos 代码库包含一组示例，展示了如何为 Electron 应用添加功能。这些信息应包含在“为应用添加功能”指南中，以便与单一可信来源内容策略保持一致。 5. 将 Electron Fiddle 示例集成到文档中。通过此步骤，新开发者可以更轻松地了解特定代码的运作方式，而无需手动重复步骤。集成包括为更新后的教程编写代码示例，并向代码块添加“在 Fiddle 中启动”按钮。
赛况
申请审核期 - 熟悉社区和同事。了解社区贡献指南和最佳实践。做出第一批贡献。 社区互动 - 探索社区。检查 Electron 文档的当前状态。找出薄弱点。 第 1 周 - 与导师就项目里程碑和交付成果达成一致 第 2 周 - 修改“开发者环境”和“编写您的第一个 Electron 应用”页面 第 3 周 - 修改“应用架构”“向应用添加功能”“应用打包和分发”页面。创建一个摘要页面，列出可添加到应用的功能 第 4 周 - 调整文档目录 第 5 周 - 准备一个模板，说明如何将 electron-api-demos 集成到主文档中 第 6 - 7 周 - 迁移 electron-api-demos 仓库 第 8 周 - 准备一个模板，说明 Electron Fid 如何集成到主文档中。编写第一个示例。 第 9 周至第 10 周 - 将 Electron Fiddle 集成到主要文档中 第 11 周 - 迁移 electron-api-demos 代码库和 Electron Fiddle 示例后，最终确定主要文档结构和页面 第 12 周 - 评估结果
里程碑的详细细分数据
申请审核期 该期限的前半部分将专门用于检查社区渠道和源代码，并与专门负责该项目的人员联系。
该阶段的第二部分将专门用于检查贡献文化，并审核贡献指南和最佳实践。这将是首次贡献内容，以了解该流程的运作方式。
社区凝聚力
本课将深入探讨文档文件夹及其路线图。基于这些信息，您可以找出可以改进的弱点（例如，不完整或缺失的部分）。创建拉取请求（如有可能）来填补空白。
第 1 周 - 第 2 周
第一周将专门用于与导师沟通，以便就预期的里程碑和及时交付事宜达成一致。
第二周将介绍“开发者环境”和“编写您的第一个 Electron 应用”页面。 对于“开发者环境”页面，将包括重写一般概览和校对。 对于“编写您的第一个 Electron 应用”页面，改进包括将该页面打造为具有明确起点和终点且步骤一致的分步指南，并移除冗余信息（例如“Electron 开发概要”和“试用此示例”部分下方两个类似的代码块）。
交付项：已修订且易于遵循的介绍指南，介绍如何快速入门 Electron 应用。
第 3 周
本周将重点介绍： 1. 改进“应用架构”页面。具体包括： - 重写了“Main 和 Renderer 进程”部分中的现有信息，以便首次阅读者更轻松、更直观地了解这些信息 - 添加了架构的直观表示，包括进程的连接方式、通信方式以及它们的核心区别。视觉效果示例：一、二、三（质量较差）。 2. 统一了您可以添加到 Electron 应用中的所有功能的相关信息。这包括重写指南，使其包含一组统一的有关如何安装/启用功能的说明，以及该功能运作方式的示例。此外，系统还会创建一个新页面（摘要），其中列出了所有可用的功能。 统一说明可能如下所示： - 概览 - 示例： - 代码示例 - 直观示例（如有可能）
- 简化了“应用分发”页面。具体包括： a. 将“应用打包”合并到“应用分发”指南中 b. 将分发方法划分为自动和手动分发 c. 将 electron-forge 作为自动分发的示例 d. 从“应用打包”页面中获取有关 asar 的信息，并将复制源文件和创建 asar 归档作为手动分发的示例。 #### 第 4 周 本周将专门用于调整文档目录的结构。It includes:
1 - 将现有指南至少划分为三类： a. 快速入门 b. 了解基础知识 c. 高级步骤
“快速入门”类别包含基本教程（安装、配置、分发），用于创建一系列一致的指南，帮助新手从头开始快速入门。每本指南都应包含指向该系列中前一/后一指南的链接。
结构可能如下所示： 1. 前提条件 2. 安装 Electron 3. 创建基本应用 4. 打包/分发应用
完成“快速入门”部分后，用户将了解 Electron 应用的工作原理基础，并拥有一个完全可用的分发式 Electron 应用。
“学习基础知识”类别将包含旨在加强对 Electron 的了解并扩展在“快速入门”部分中创建的应用的指南。这些指南包括： - 应用架构 - 为应用添加功能 - 样板和 CLI
“高级步骤”类别将包含更多高级指南，旨在帮助您配置和微调 Electron 应用： - 测试和调试 - 无障碍功能 - 安全性 - 更新
2 - 减少文档页面数量。当前版本的文档包含一定程度的重叠内容和未分类的说明。例如： - 在“编写您的第一个应用”中安装和安装 Electron - 将应用打包并打包到应用分发内的文件中 -“详细信息”和“高级”类别中的未分类说明： 建议：将以下文档移至 GitHub，并从主文档中排除。以下文档专门介绍了 Electron 开发指南，源代码库是查找这些文档的首选位置： - 开发 Electron - Chromium 开发 - V8 开发 - Electron 中的问题 - Electron 中的补丁 - 拉取请求 - 源代码目录结构 - 测试 - 编码风格
减少文档数量的主要目的是减少大量可用指南，将散落的信息拼图拼接在一起，为新手提供更结构化、更易于浏览且更易于使用的 Electron 文档版本。
第 5-7 周
第 5 周将专门用于准备将 electron-api-demos 集成到主要文档中的模板（方法）。此模板可能如下所示： 1. 在主要文档的“向应用添加功能”下，创建 electron-api-demos 中所代表的类别 2. 浏览每个类别，将演示示例转移到主要文档： - 代码示例可以从源代码或应用中相应功能的说明中获取 - 每个转移的示例后面都应附有相关说明 - 每个子示例（例如，作为“使用系统对话框”的子项的“错误对话框”）都应转移到其父级下
注意 1：electron-api-demo 和主文档（例如键盘快捷键、拖放）中都有相关示例。在这种情况下，electron-api-demos 中的示例应优先，而主文档中的示例应被忽略。
注意 2：electron-api-demos 应用中的许多示例都具有所描述功能的实际演示预览。在第 9-10 周集成 Electron Fiddle 之前，此功能将被忽略。
- 更新列出所有可用功能（在第 3 周创建）的页面，以遵循新的示例层次结构。
第 6 周和第 7 周将用于根据上述模板将 electron-api-demo 示例转移到主文档。最后，您应删除或废弃 electron-api-demos 代码库。
第 8 - 10 周
第 8 周将专门用于准备将 Electron Fiddle 集成到主要文档中的模板（方法）。Electron 团队和社区志愿者已启动此计划（请参阅问题 #20442 中的详细信息），但需要进行适当的最终确定。
如需继续处理 Fiddle 示例，基本模板可能如下所示： 1. 从主要文档中选择一个示例（例如，快速入门）。此时，文档还应包含 electron-api-demos 示例； 2. 在 Electron Fiddle 中重新创建示例（使用示例代码或源代码作为起点）； 将 Fiddle 保存到本地的文件夹中； 4. 将示例移至 /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]。 * 该问题的“演示列表”部分对已完成示例的列表进行了说明。 5. 添加了“在 Fiddle 中启动”按钮，如问题 #2848 中的初始注释中所述。
第 9 周和第 10 周将专门按照上述模板将 electron-api-demos 示例（已转换为 Fiddles）集成到主文档中。
第 11 周
本周，我们将全力以赴，在成功迁移 electron-api-demos 代码库和 Electron Fiddle 示例后，完成编写项目。这包括： - 检查所有现有代码示例是否都具有“在 Fiddle 中启动”按钮 - 检查所有现有代码示例是否都作为 Fiddle 正常运行 - 检查主要文档是否不再引用 electron-api-demos 代码库
第 12 周
对已完成的工作进行定稿。验收单。