本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- Electron
- 技術撰稿人：
- Mister Gold
- 專案名稱：
- 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 Fiddle 整合至主要說明文件。編寫第一個樣本。第 9 到 10 週 - 將 Electron Fiddle 整合至主要說明文件 第 11 週 - 遷移 electron-api-demos 存放區和 Electron Fiddle 範例後，完成主要說明文件結構和頁面 第 12 週 - 評估結果
里程碑詳情
申請審查期 在這個期間的最初階段，我們會檢查社群管道和原始碼，並與專責該專案的人員聯絡。
研究期間的第二部分將致力於瞭解整體捐款文化，檢視捐款指南及最佳做法。這時可以透過首次貢獻內容，瞭解流程的運作方式。
社群連結
這次我們將深入探討說明文件資料夾和其路線圖。根據這些資訊，您可以找出需要改善的弱點 (例如缺少或不完整的部分)。建立可填補空白的提取要求 (如有可能)。
第 1 週 - 第 2 週
第一週將專注於與導師溝通，以便配合預期的里程碑和及時提交。
第二週是修改開發人員環境，以及如何編寫第一個 Electron 應用程式頁面。 針對「開發人員環境」頁面，這項服務包括重寫一般總覽和校對。在「編寫您的第一個 Electron 應用程式」頁面中，我們需將網頁中的逐步指南製作成清楚的開始和端點，並移除多餘的資訊 (例如：在 Nutshell 中，Electron Development 下兩個類似的程式碼區塊，並根據這個範例部分)。
成果：修訂版的簡易操作說明指南，說明如何快速開始使用 Electron 應用程式。
第 3 週
本週的目標如下： 1. 改善「應用程式架構」頁面。這包括： - 重寫「Main」和「Renderer Processes」部分的現有資訊，讓初次閱讀者更容易理解視覺素材範例：一、二、三 (低品質)。2. 統一您可以在 Electron 應用程式中新增的所有功能相關資訊。包括重寫指南，讓他們具備一組統一的安裝/啟用操作說明，以及功能運作方式範例。此外，我們也會建立新頁面 (摘要)，列出所有可用的功能。統一的指示可能如下所示： - 概述 - 範例： - 程式碼範例 - 視覺範例 (可用時)
- 簡化「Application Distribution」頁面。包括： 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 範例整合至主要說明文件。這個範本可能如下所示： 1. 在主要說明文件的「新增應用程式功能」下方，建立 electron-api-demos 中的類別。 2. 逐一檢查各個類別，將示範範例轉移至主要文件： - 程式碼範例可從原始碼或應用程式中對應功能的說明中取得 - 每個轉移的範例後面都應附上相關說明 - 每個子項範例 (例如「使用系統對話方塊」的子項「錯誤對話方塊」) 應轉移至其父項下方
注意事項 #1：在 electron-api-demos 和主要說明文件中，都會提供相關範例 (例如鍵盤快速鍵、拖曳和放置)。在這種情況下，應優先採用 electron-api-demos 中的範例，並忽略主要文件中的範例。
注意 #2：electron-api-demos 應用程式中的許多範例提供所述功能的即時示範預覽畫面。在第 9 到 10 週的 Electron Fiddle 整合作業完成前，系統會忽略這項功能。
- 依新的範例階層更新頁面，列出第 3 週建立的所有可用功能。
第 6 和 7 週將專注於根據上述範本，將 Electron API 範例轉移至主要文件。最後，您應刪除或淘汰 electron-api-demos 存放區。
WEEKS 至 10 週
第 8 週將專門準備範本 (一種方法)，說明如何將 Electron Fiddle 整合至主要說明文件。這項計畫已經由 Electron 成員和社群志工所發起 (請查看問題 #20442 的詳細資訊)，但需要經過妥善的最終定案。
如要繼續使用 Fiddle 範例，基本範本可能會如下所示： 1. 從主要文件中選擇範例 (例如快速入門)。目前，說明文件也應包含 electron-api-demos 範例；2. 在 Electron Fiddle 中重建範例 (使用範例程式碼或原始碼做為起點)；將 Fiddle 儲存至本機資料夾；將範例移至 /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]。* 在問題的「示範模式清單」部分下方，會列出已完成的範例。 5. 按照問題 #2848 的初始註解所述，新增「Launch in Fiddle」按鈕。
第 9 週和第 10 週將專注於根據上述範本，將已轉換為 Fiddle 的 electron-api-demos 範例整合至主要文件。
第 11 週
本週將全力投入，在成功遷移 electron-api-demos 存放區和 Electron Fiddle 範例後，完成撰寫專案。包括： - 檢查所有現有的程式碼範例是否都有「在 Fiddle 中啟動」按鈕 - 檢查所有現有的程式碼範例是否能正常運作為 Fiddle - 檢查主要文件是否不再參照 electron-api-demos 存放區
第 12 週
完成工作並完成結算。接受檢查。