本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- Electron
- 技術文件撰寫者：
- Mister Gold
- 專案名稱：
- Electron 教學課程流程
- 專案長度：
- 標準長度 (3 個月)
Project description
專案摘要
Electron 是最常用的工具之一，能夠利用 JavaScript、HTML 和 CSS 建構跨平台的電腦版應用程式。以 Electron 為基礎打造的一系列應用程式目前已有將近 900 個項目，這份清單仍在持續增加中。許多最熱門的開發人員工具皆採用 Electron 開發而成，例如 Visual Studio Code、Atom、Postman、Slack。
Electron 的熱門程度僅仰賴簡單的學習曲線和入門門檻，所有熟悉 JavaScript、HTML 和 CSS 堆疊的人都能建構自己的應用程式。整體成長率極大，決定了建立教學課程和入門指南的需求，可輕鬆掌握及使用。
這項計畫的目標是讓剛接觸 Electron 架構的應用程式建構工具能安心使用，從基礎開發自家的 Electron 應用程式時，提供一致且流暢的體驗。
專案問題
以下是與 Electron 教學課程說明文件相關的最重大問題： 1. 關於應用程式開發步驟的起點，以及不符合直覺的起點 2. 與應用程式開發程序相關的分散和備援資訊 3. 整理完整的「入門指南」操作說明，且只提供單一資料來源
專案提案
根據專案的目標和上述問題，以下是建議的強化項目清單： 1. 更新現有指南。為使前所處步驟更加流暢並一致，您應更新下列文件，逐步從簡單變更為更複雜的程式碼： - 開發人員環境 - 編寫第一個 Electron 應用程式 - 在應用程式中新增功能 (建立摘要頁面) - 應用程式套件與發布 2. 重組說明文件目錄。為了向新手開發人員說明開始使用的必備要素以及可額外進行的操作，文件頁面應包含相關步驟，讓第一個應用程式盡快上線。重組程序也包含後續步驟指引。3. 整理並統整應用程式開發說明文件。所有功能都應提供一套統合的操作說明，讓您瞭解如何安裝/啟用這項功能、如何快速開始使用、如何在首次啟動後使用應用程式，以及如何發布應用程式。4. 在說明文件中加入 Elron-api-demos 存放區。Elron-api-demos 存放區包含一組範例，說明如何為 Electron 應用程式新增功能。「在應用程式中新增功能」指南中應包含這些資訊，必須與單一可靠資料來源策略一致。5. 在說明文件中整合 Electron Fiddle 範例。這個步驟可讓新開發人員更輕鬆地查看特定程式碼的運作方式，而不必手動執行這些步驟。這項整合功能包含為新版教學課程編寫程式碼範例，以及將「在 Fiddle 中啟動」按鈕新增至程式碼區塊。
賽況
申請審查期 - 熟悉社群和合作人員。瞭解社群貢獻指南和最佳做法。首次貢獻內容。 社群凝聚力 - 探索社群。檢查 Electron 說明文件的目前狀態。找出弱點。第 1 週 - 與導師合作達成專案里程碑和交付項目 第 2 週 - 修改開發人員環境及編寫第一個 Electron 應用程式頁面 第 3 週 - 修改應用程式架構、為應用程式、應用程式套件和發行頁面新增功能。建立摘要頁面，列出可新增至應用程式的功能 第 4 週 - 重新建構說明文件目錄 第 5 週 - 準備範本，說明將電子 API 示範如何整合至主要說明文件 第 6 至 7 週 - 遷移電子產品說明文件 第 8 週 - 準備將 Electron Fiddle 整合至主要說明文件的範本。編寫第一個範例。 第 9 至 10 週 - 將 Electron Fiddle 整合至主要說明文件 第 11 週 - 遷移 Electron 示範存放區和 Electron Fiddle 樣本後，主要說明文件結構和頁面 第 12 週 - 評估結果
里程碑細目
申請審查 期間的第一部分將負責檢查社群頻道和原始碼，以及聯絡專案專用人員。
活動期間的第二部分將致力檢視所有貢獻文化，並審視貢獻指南和最佳做法。這是首次貢獻內容，瞭解流程的運作方式。
社群凝聚
我們會利用這段時間進一步檢視說明文件資料夾及其發展藍圖。根據這項資訊，我們可以找出哪些弱點 (例如不完整或遺漏部分) 有待改進。在可能的情況下建立提取要求來填補缺口。
第 1 週 - 第 2 週
第一週將投入心力與導師溝通，以達成預期的里程碑並準時交付。
第二週的主題是修改開發人員環境，以及如何編寫第一個 Electron 應用程式頁面。針對「開發人員環境」頁面，內容包含重新撰寫一般總覽和校對功能。至於「編寫您的第一個 Electron 應用程式」頁面，您需要在頁面中設定與開始和結束點一致的逐步指南，移除多餘的資訊 (例如，在 Nutshell 中執行 Electron 開發的兩個類似程式碼區塊，並試玩這個範例一節)。
交付項目：修訂後易於遵循的簡介指南，協助您瞭解如何使用 Electron 應用程式快速上手。
第 3 週
本週的主題是： 1.「應用程式架構」頁面的改善項目。這包括： - 重新編寫「主要與轉譯器程序」部分中的現有資訊，讓初次讀者操作更簡單直覺，例如以視覺化方式呈現架構、程序的連接方式、程序通訊方式及核心差異。影像示例：一、二、三 (低品質)。2. 針對可新增至 Electron 應用程式的所有功能整合相關資訊。這包括重新編寫指南，請他們針對如何安裝/啟用特定功能，以及功能運作方式示例，進行統一的一系列操作說明。此外，系統也會建立新的頁面 (摘要)，列出所有可用功能。 統一操作說明可能如下所示： - 總覽 - 範例： - 程式碼範例 - 視覺範例 (可能的話)
- 簡化「應用程式發布」頁面。其中包括：a. 將應用程式封裝合併到應用程式發布指南中。b. 將發行方法分成自動和手動 c. 以自動發布方式進行電子化：從「應用程式封裝」頁面擷取資訊，並描述複製來源檔案和建立做為手動發布的範例。#### WEEK 4 本週將會專門重組說明文件目錄。本指南涵蓋的內容：
1 - 將現有指南分成至少三個類別： a. 快速入門導覽課程 b. 學習基本資訊 c. 進階步驟
「快速入門導覽課程」類別包含基本教學課程 (安裝、設定、發布)，建立一系列一致的指南，讓新手能從頭開始開始快速入門導覽課程。每一份指南都應該提供該系列中上一頁/下一份指南的連結。
結構可能如下： 1. 必要條件 2. 安裝 Electron 3. 建立基本應用程式 4. 封裝/發布應用程式
完成「快速入門導覽課程」部分後，使用者將瞭解 Electron 應用程式的基本運作方式，並可取得可完整發布的 Electron 應用程式。
「學習基礎知識」類別包含指南，旨在充實 Electron 相關知識，並延伸在「快速入門導覽課程」章節中建立的應用程式。這些指南包括： - 應用程式架構 - 在應用程式中新增功能 - 樣板和 CLI
「進階步驟」類別包含更進階的指南，說明如何設定及微調 Electron 應用程式： - 測試和偵錯 - 無障礙功能 - 安全性 - 更新
2 - 減少說明文件頁面數量。目前的說明文件版本包含一定程度的重疊內容和未分類操作說明。例如： - 在編寫第一個應用程式的過程中安裝及安裝 Electron - 應用程式封裝以及將應用程式封裝至應用程式發布的檔案中 - 「詳細資訊」和「進階」類別中的未分類操作說明： 建議：將下列文件移至 GitHub，並從主要說明文件中排除。這些文件是專門針對 Electron 開發指南提供，因此要優先查看原始碼存放區： - 開發 Electron - Chromium 開發作業 - V8 開發 - Electron 中的問題 - Electron 中的修補程式 - 提取結構要求 - 程式設計樣式
這個 API 縮減提案的主要用意是捨棄大量可用的指南，藉此彙整零碎的內容，為新手提供更結構、易於瀏覽且容易使用的 Electron 說明文件版本。
第 5 週至 7 週
第 5 週將會專門準備範本，也就是將電子 API 示範整合至主要文件的方式。這個範本的外觀如下： 1. 在主要說明文件的「Add Features to Your App」下方，建立 Elron-api-demos 所代表的類別。 2. 瀏覽每個類別，將示範範例轉移至主要說明文件： - 程式碼範例可從原始碼或應用程式中對應功能的說明取得 - 每個移轉的範例後面都要接上相關聯的說明 - 每個子項範例 (例如將「使用系統」對話方塊做為「使用」系統對話方塊的子項) 應轉移至其父項下方
注意 #1：在 Elron-api-demo 中和主要說明文件 (例如鍵盤快速鍵、拖曳) 中都有範例。在這個情況下，Eron-api-demos 的範例應以優先順序為準，並忽略主要說明文件中的示例。
注意 #2：在 Elron-api-demos 應用程式中，許多範例提供已描述功能的即時展示模式預覽。在第 9 至 10 週進行 Electron Fiddle 整合之前，系統會忽略這項功能。
- 根據新的範例階層，更新頁面列出所有可用功能 (在第 3 週建立的功能)。
第 6 週和第 7 週將專門根據上述範本，將電子 API 範例轉移至主要說明文件。最後一步是刪除或淘汰 Elron-api-demos 存放區。
第 8 週至 10 週
第 8 週將會專門準備將 Electron Fiddle 整合至主要說明文件的範本 (一種方法)。這項計畫已由 Electron 員工與社群志工公開 (請查看問題 #20442) 已推出，但需要經過審慎規劃。
繼續執行 Fiddle 範例時，基本範本可能如下所示： 1. 從主要說明文件中選擇範例 (例如快速入門導覽課程)。此時，說明文件應包含 Elron-api-demos 範例； 2. 在 Electron Fiddle 中重新建立範例 (使用範例程式碼或原始碼做為起點)；3. 將 Fiddle 儲存在本機資料夾； 4. 將範例移至 /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]。 * 完整樣本清單列載於問題的「示範清單」一節中。 5. 按照問題 #2848 中的初始留言所述，新增「在 Fiddle 中啟動」按鈕。
第 9 和第 10 週將專門根據上述範本，將電子 API 示範 (已轉換為 Fiddles) 與主要說明文件整合。
第 11 週
成功遷移 Electron Fiddle 樣本後，本週將完全專注於完成寫入專案。這包括： - 確認所有現有的程式碼範例都有「在 Fiddle 中啟動」按鈕 - 確認所有現有的程式碼範例都能做為 Fiddles 正常運作 - 確認主要說明文件已不再參照 Elron-api-demos 存放區
第 12 週
已完成工作。接受檢查。