本页面包含有关 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. 与应用开发流程相关的散乱信息 3. “使用入门”指南说明内容条理清晰，没有单一的可信来源
项目提案
根据该项目的目标和上述问题，下面列出了建议的增强功能： 1. 更新现有指南。为使最初的步骤顺畅且一致，以下文档应逐步从简单改为更复杂的功能： - 开发环境 - 编写您的第一个 Electron 应用 - 向您的应用添加功能（创建摘要页面） - 应用打包和分发 2. 重构文档目录。为向新开发者展示入门必不可少以及哪些操作可以视为后续步骤，文档页面应在视觉上和上下文中分别提供各个步骤，以便尽快发布第一个应用。结构调整还包括关于后续可能步骤的指南。 3. 整理和统一应用开发文档。所有功能都应提供一套统一的说明，说明如何安装/启用应用、如何快速开始使用应用、在首次启动后如何使用应用以及如何分发应用。 4. 在文档中添加 email-api-demos 代码库。email-api-demos 代码库包含一组示例，展示了如何向 Electron 应用添加功能。此信息应包含在“向应用添加功能”指南中，以便与单一可靠内容策略保持一致。 5. 将 Electron Fiddle 示例集成到文档中。此步骤可让新开发者更轻松地了解特定代码的工作原理，而无需手动重复这些步骤。集成工作包括为更新教程编写代码示例，以及向代码块中添加“Launch in Fiddle”按钮。
赛况
申请期限 - 熟悉社区和合作人员。了解社区贡献指南和最佳实践。进行首次贡献。 社区凝聚力 - 探索社区。检查 Electron 文档的当前状态。找出薄弱点。 第 1 周 - 与导师就项目里程碑和交付成果达成一致 第 2 周 - 修改开发环境和编写您的首个电子应用页面 第 3 周 - 修改应用架构、向您的应用添加功能、应用打包和分发页面。创建摘要页面，列出可添加到应用的功能列表 第 4 周 - 重新构建文档目录 第 5 周 - 准备将 Electron-api-demos 集成到主文档中的模板 第 6-7 周 - 迁移 email-api-demos 代码库 第 8 周 - 准备说明 Electron Fiddle 将如何集成到主文档中的模板。编写第一个样本。 第 9 - 10 周 - 将 Electron Fiddle 集成到主文档中 第 11 周 - 在迁移 email-api-demos 代码库和 Electron Fiddle 示例后最终完成主文档结构和页面 第 12 周 - 评估结果
里程碑的详细细分数据
申请审核期 第一部分将专门用于检查社区频道和源代码，并与项目负责人联系。
课程的第二部分将用于了解总体贡献文化，以及贡献指南和最佳做法。您可以在此期间进行首次贡献，了解该流程的运作方式。
社区凝聚
在此期间，我们将深入探讨该文档文件夹及其路线图。根据这些信息，我们才能够找出有待改进的薄弱点（例如不完整或缺失）。创建拉取请求（如果可能）来填补这些缺口。
第 1 周 - 第 2 周
第一周主要用于与导师沟通交流，以便就预期的里程碑和及时交付方面达成一致。
第二周我们将介绍如何修订开发环境和编写您的第一个 Electron 应用页面。对于“开发者环境”页面，它将包括重写概述和校对。 对于“编写您的第一个 Electron 应用”页面，这将包括使页面成为一致的分步指南，并明确起点和终点，并移除多余的信息（例如“在 Nutshell 中 Electron Development”下的两个相似代码块和“Trying this example”部分）。
交付成果：经过修订且简单易懂的介绍指南，了解如何快速入门 Electron 应用。
第 3 周
本周，我们将介绍以下内容： 1. 改进“应用架构”页面。这包括： - 重写了“Main Processes”和“Renderer Processes”部分中的现有信息，让初次使用者能够更直观和简单地了解相关信息 - 添加架构、进程连接方式、通信方式及其核心区别的视觉表示形式。视觉元素示例：One、2、3（低画质）。 2. 统一可添加到 Electron 应用中的所有功能的信息。这包括重新编写指南，为他们提供有关如何安装/启用功能的一组统一说明，以及功能运作方式示例。此外，系统还会创建一个列出所有可用功能的新页面（摘要）。 统一说明可能如下所示： - 概览 - 示例： - 代码示例 - 直观示例（如果可能）
- 简化了“应用分发”页面。这包括：a. 将应用打包合并到应用分发指南中 b. 将分发方法分为自动分发和手动分发方法 c. 以电子伪造为示例进行自动分发 d. 从“应用打包”页面获取有关 Asar 的信息，并说明复制源文件和创建 asar 归档文件作为手动分发的示例。#### 第 4 周 这周的主题是调整文档目录。包括：
1 - 将现有指南至少划分为三个类别： a. 快速入门 b. 了解基础知识 c. 高级步骤
“快速入门”类别将包含基础教程（安装、配置、分发），创建一系列一致的指南，让新手能够从头开始快速入门。每个指南都应包含系列中上/下指南的链接。
具体结构可能如下所示： 1. 前提条件 2. 安装 Electron 3. 创建基本应用 4. 打包/分发应用
完成“快速入门”部分后，用户将了解 Electron 应用运作方式方面的基础知识，并且将拥有一个完全正常运行的可分发 Electron 应用。
“学习基础知识”类别中包含一些指南，旨在强化对 Electron 的了解以及扩展在“快速入门”部分创建的应用。这些指南包括： - 应用架构 - 向您的应用添加功能 - 样板和 CLI
“高级步骤”类别将包含旨在配置和微调 Electron 应用的更高级指南： - 测试和调试 - 无障碍功能 - 安全性 - 最新动态
2 - 减少文档页数。当前版本的文档包含一定程度的重叠内容和未分类的说明。例如： - 在编写首个应用的过程中安装和安装 Electron - 在应用分发中将您的应用打包和打包到文件中 - “详细说明”和“高级”类别中的未分类说明： 建议：将以下文档移至 GitHub 并从主文档中排除。这些文档专门针对 Electron 开发指南，应首先在源代码库中查找： - Developing Electron - Chromium Development - V8 Development - Electron 中的问题 - Electron 中的补丁 - 拉取请求 - 源代码目录结构 - 测试 - 编码样式
这样做的主要目的是舍弃大量可用的指南，将分散的拼图信息连在一起，为新用户提供更有条理、更易于导航且人性化的 Electron 文档版本。
第 5 - 7 周
第 5 周将专门准备一个模板（一种方式），说明 email-api-demos 将如何集成到主文档中。此模板可能如下所示： 1. 在主文档中，在“Added Features to Your App”下，创建 email-api-demos 中表示的类别。 2. 逐一了解每个类别，将演示示例转移到主文档中： - 代码示例可以从源代码或应用中相应功能的说明中获取 - 每个转移的示例后接相应的说明 - 每个子示例（例如，作为“使用系统对话框”子项的“错误”对话框）应转移在其父级下
注意 #1：Electrron-api-demos 和主文档中都存在一些示例（例如键盘快捷键、拖放）。在这种情况下，应该优先使用 email-api-demo 中的示例，而应忽略主文档中的示例。
注意 2：Electrron-api-demos 应用中的许多示例都有所描述特性或功能的实时演示预览。在第 9-10 周集成 Electron Fiddle 之前，此功能将被忽略。
- 更新列出所有可用功能（在第 3 周创建）的页面，遵循新的示例层次结构。
第 6 周和第 7 周将专门根据上述模板将 email-api-demos 示例转移到主文档中。最后，应删除或废弃 emailron-api-demos 代码库。
第 8 - 10 周
第 8 周将专门准备一个模板（一种方式），说明 Electron Fiddle 将如何集成到主文档中。这一计划已经由 Electron 团队和社区志愿者启动（请查看问题 20442 中的详细信息），但需要适当的敲定。
要继续学习 Fiddle 示例，基本模板可能如下所示： 1. 从主文档中选择一个示例（例如快速入门）。此时，文档中还应包含 email-api-demos 示例； 2. 在 Electron Fiddle 中重新创建示例（使用示例代码或源代码作为起点）； 3. 将 Fiddle 在本地文件夹中保存到一个文件夹中； 4. 将示例移至 /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]。 * 该问题的“演示列表”部分对已完成的示例列表进行了说明。 5. 按照问题 2848 中的初始评论中的说明，添加“Launch in Fiddle”（在 Fiddle 中启动）按钮。
第 9 和第 10 周将专门按照上述模板将 Electrron-api-demos 示例（已转换为 Fiddles）整合到主文档中。
第 11 周
本周，我们将全心投入在成功迁移电子 API 演示库和 Electron Fiddle 示例后完成的写作项目。这包括： - 检查所有现有代码示例是否都有“Launch in Fiddle”按钮 - 检查所有现有代码示例是否都能以 Fiddles 的形式正常运行 - 检查主文档是否不再引用 emailron-api-demos 仓库
第 12 周
已完成的工作定稿。验收检查。