โครงข่ายอิเล็กตรอน

หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs

สรุปโปรเจ็กต์

องค์กรโอเพนซอร์ส:

Electron

นักเขียนเชิงเทคนิค:

Mister Gold

ชื่อโปรเจ็กต์:

ขั้นตอนการแนะนำ Electron

ระยะเวลาของโปรเจ็กต์

ระยะเวลามาตรฐาน (3 เดือน)

คำอธิบายโปรเจ็กต์

สรุปโครงการ

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. อัปเดตคู่มือที่มีอยู่ เพื่อให้ขั้นตอนแรกเป็นไปอย่างราบรื่นและสอดคล้องกัน คุณควรอัปเดตเอกสารต่อไปนี้โดยค่อยๆ เปลี่ยนจากเรียบง่ายเป็นซับซ้อนมากขึ้น - สภาพแวดล้อมของนักพัฒนาซอฟต์แวร์ - การเขียนแอปอิเล็กตรอนเป็นครั้งแรก - การเพิ่มฟีเจอร์ลงในแอปของคุณ (สร้างหน้าสรุป) - การจัดแพ็กเกจและการจัดจำหน่ายแอป 2. ปรับโครงสร้างไดเรกทอรีเอกสารประกอบใหม่ หน้าเอกสารควรแบ่งขั้นตอนออกเป็นทั้งภาพและตามบริบทเพื่อให้นักพัฒนาแอปมือใหม่เห็นสิ่งที่จําเป็นต่อการเริ่มต้นใช้งานและสิ่งที่ถือเป็นขั้นตอนถัดไป เพื่อให้แอปพลิเคชันแรกเผยแพร่ได้เร็วที่สุด การปรับโครงสร้างยังรวมคำแนะนำเกี่ยวกับขั้นตอนถัดไปที่เป็นไปได้ด้วย 3. จัดระเบียบและรวมเอกสารประกอบการพัฒนาแอปพลิเคชัน ฟีเจอร์ทั้งหมดควรมีชุดวิธีการแบบรวมกันเกี่ยวกับวิธีติดตั้ง/เปิดใช้ วิธีเริ่มต้นใช้งานอย่างรวดเร็ว วิธีใช้งานแอปหลังจากเปิดใช้งานครั้งแรก และวิธีเผยแพร่ 4. ใส่ที่เก็บ electron-api-demos ในเอกสารประกอบ ที่เก็บ electron-api-demos มีชุดตัวอย่างที่แสดงวิธีเพิ่มฟีเจอร์ลงในแอปพลิเคชัน Electron ข้อมูลนี้ควรรวมอยู่ในคู่มือการเพิ่มฟีเจอร์ลงในแอปเพื่อให้สอดคล้องกับกลยุทธ์เนื้อหาแหล่งข้อมูลเดียว 5. ผสานรวมตัวอย่าง Electron Fiddle ไว้ในเอกสารประกอบ ขั้นตอนนี้จะช่วยให้นักพัฒนาแอปมือใหม่เห็นการทำงานของโค้ดแต่ละส่วนได้ง่ายขึ้นโดยไม่ต้องทำซ้ำด้วยตนเอง การผสานรวมนี้ประกอบไปด้วยการเขียนตัวอย่างโค้ดสำหรับบทแนะนำที่อัปเดตใหม่ และเพิ่มปุ่ม "Launch in Fiddle" ลงในโค้ดบล็อก

ไทม์ไลน์

ระยะเวลาตรวจสอบใบสมัคร - ทำความคุ้นเคยกับชุมชนและคนที่จะร่วมงานด้วย ดูคู่มือและแนวทางปฏิบัติแนะนำเกี่ยวกับการมีส่วนร่วมของชุมชน มีส่วนร่วมครั้งแรก การสร้างความสัมพันธ์ในชุมชน - สำรวจชุมชน ตรวจสอบสถานะปัจจุบันของเอกสารเกี่ยวกับอิเล็กตรอน ระบุจุดอ่อน สัปดาห์ที่ 1 - ปรับเป้าหมายและส่งมอบโปรเจ็กต์ให้สอดคล้องกับที่ปรึกษา สัปดาห์ที่ 2 - แก้ไขหน้าสภาพแวดล้อมของนักพัฒนาซอฟต์แวร์และการเขียนแอป Electron แรก สัปดาห์ที่ 3 - แก้ไขสถาปัตยกรรมแอปพลิเคชัน การเพิ่มฟีเจอร์ลงในแอป การสร้างแพ็กเกจแอป และการเผยแพร่ สร้างหน้าสรุปพร้อมรายการฟีเจอร์ที่เพิ่มลงในแอปได้ สัปดาห์ที่ 4 - ปรับโครงสร้างไดเรกทอรีเอกสารประกอบใหม่ สัปดาห์ที่ 5 - เตรียมเทมเพลตของวิธีผสานรวม electron-api-demos เข้ากับเอกสารประกอบหลัก สัปดาห์ที่ 6-7 - ย้ายข้อมูลรีโพซิทอรี่ electron-api-demos สัปดาห์ที่ 8 - เตรียมเทมเพลตของวิธีผสานรวม Electron Fiddle เข้ากับเอกสารประกอบหลัก เขียนตัวอย่างแรก สัปดาห์ที่ 9 - 10 - ผสานรวมอิเล็กตรอนฟิดเดิลเข้ากับเอกสารหลัก สัปดาห์ที่ 11 - สรุปโครงสร้างและหน้าเอกสารหลักหลังจากย้ายที่เก็บชุดการสาธิตอิเล็กตรอน API และตัวอย่างฟิดเดิลอิเล็กตรอน สัปดาห์ที่ 12 - การประเมินผลลัพธ์

รายละเอียดของเหตุการณ์สำคัญ

ระยะเวลาการตรวจสอบใบสมัคร ช่วงแรกของระยะเวลานี้จะเน้นไปที่การตรวจสอบแชแนลชุมชนและซอร์สโค้ด รวมถึงติดต่อผู้ที่ทุ่มเทให้กับโปรเจ็กต์

ส่วนที่สองของระยะเวลานี้จะเน้นไปที่การตรวจสอบวัฒนธรรมการมีส่วนร่วมโดยทั่วไป การตรวจสอบคู่มือการมีส่วนร่วมและแนวทางปฏิบัติแนะนำ นี่เป็นเวลาที่จะให้เนื้อหาสนับสนุนเป็นครั้งแรกเพื่อดูว่าขั้นตอนทำงานอย่างไร

การสานสัมพันธ์ในชุมชน

ในระหว่างนี้ เราจะตรวจสอบโฟลเดอร์เอกสารประกอบและแผนกลยุทธ์อย่างละเอียด ข้อมูลดังกล่าวจะช่วยให้คุณระบุจุดอ่อน (เช่น เนื้อหาไม่สมบูรณ์หรือขาดหายไป) ที่ปรับปรุงได้ สร้างคำขอพุล (เมื่อเป็นไปได้) เพื่อเติมเต็มช่องว่าง

สัปดาห์ที่ 1 - สัปดาห์ที่ 2

สัปดาห์แรกจะเน้นที่การสื่อสารกับที่ปรึกษาเพื่อปรับเป้าหมายระยะกลางที่คาดไว้และการส่งมอบให้ตรงเวลา

สัปดาห์ที่ 2 จะเกี่ยวกับการแก้ไขหน้า "สภาพแวดล้อมของนักพัฒนาแอป" และ "การเขียนแอป Electron รายการแรก" สำหรับหน้าสภาพแวดล้อมของนักพัฒนาแอป จะมีการเขียนภาพรวมทั่วไปและพิสูจน์อักษรอีกครั้ง สำหรับหน้าการเขียนแอป Electron รายการแรก จะมีการทำให้หน้านี้เป็นคู่มือแบบทีละขั้นตอนที่สอดคล้องกันโดยมีจุดเริ่มต้นและจุดสิ้นสุดที่ชัดเจน รวมถึงนำข้อมูลที่ซ้ำซ้อนออก (เช่น บล็อกโค้ดที่คล้ายกัน 2 บล็อกในส่วนการพัฒนา Electron โดยย่อและส่วนลองใช้ตัวอย่างนี้)

สิ่งที่ส่ง: คู่มือแนะนำฉบับปรับปรุงที่เข้าใจง่ายเกี่ยวกับวิธีเริ่มต้นใช้งานแอปพลิเคชัน Electron

สัปดาห์ที่ 3

สัปดาห์นี้เราจะมุ่งเน้นที่การพัฒนาหน้าสถาปัตยกรรมแอปพลิเคชัน ซึ่งประกอบด้วย - การเขียนข้อมูลที่มีอยู่แล้วใหม่ในส่วน "กระบวนการหลักและ" ของโหมดแสดงภาพเพื่อให้ผู้อ่านครั้งแรกสะดวกและง่ายขึ้น - การเพิ่มการนำเสนอภาพสถาปัตยกรรม ความเชื่อมโยงระหว่างกระบวนการต่างๆ วิธีการสื่อสาร และความแตกต่างหลัก ตัวอย่างภาพ: 1, 2, 3 (คุณภาพต่ำ) 2. การรวมข้อมูลเกี่ยวกับคุณลักษณะทั้งหมดที่คุณสามารถเพิ่มในแอปพลิเคชันอิเล็กตรอนของคุณได้ ซึ่งรวมถึงการเขียนคู่มือใหม่เพื่อให้มีชุดวิธีการที่เหมือนกันเกี่ยวกับวิธีติดตั้ง/เปิดใช้ฟีเจอร์ พร้อมตัวอย่างวิธีการทำงานของฟีเจอร์ นอกจากนี้ ระบบจะสร้างหน้าใหม่ (ข้อมูลสรุป) ที่แสดงฟีเจอร์ทั้งหมดที่ใช้ได้ วิธีการแบบรวมอาจมีลักษณะดังนี้ - ภาพรวม - ตัวอย่าง - ตัวอย่างโค้ด - ตัวอย่างภาพ (หากเป็นไปได้)

1. การลดความซับซ้อนของหน้าการเผยแพร่แอปพลิเคชัน ซึ่งรวมถึงการรวมการบรรจุแอปพลิเคชันไว้ในคู่มือการจัดจำหน่ายแอปพลิเคชัน การแบ่งวิธีการจัดจำหน่ายออกเป็นแบบอัตโนมัติและแบบด้วยตนเอง การใช้ electron-forge เป็นตัวอย่างของการจัดจำหน่ายแบบอัตโนมัติ การใช้ข้อมูลเกี่ยวกับ asar จากหน้าการบรรจุแอปพลิเคชันและอธิบายการคัดลอกไฟล์ต้นทางและการสร้างไฟล์เก็บถาวร asar เป็นตัวอย่างของการจัดจำหน่ายด้วยตนเอง #### สัปดาห์ที่ 4 สัปดาห์นี้จะเน้นไปที่การปรับโครงสร้างไดเรกทอรีเอกสารประกอบ แอปประกอบด้วย

1 - แบ่งคู่มือที่มีอยู่อย่างน้อย 3 หมวดหมู่ ดังนี้ ก. การเริ่มต้นอย่างรวดเร็ว ข. การเรียนรู้พื้นฐาน ค. ขั้นตอนขั้นสูง

หมวดหมู่ "เริ่มต้นใช้งาน" จะมีบทแนะนำพื้นฐาน (การติดตั้ง การกําหนดค่า การเผยแพร่) เพื่อสร้างชุดคู่มือที่สอดคล้องกัน ซึ่งจะช่วยให้ผู้มาใหม่เริ่มต้นใช้งานตั้งแต่ต้นได้ คู่มือแต่ละเล่มควรมีลิงก์ไปยังคู่มือก่อนหน้า/ถัดไปในชุด

โครงสร้างอาจมีลักษณะดังนี้ 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-demos และในเอกสารประกอบหลัก (เช่น แป้นพิมพ์ลัด การลากและวาง) ในกรณีนี้ ตัวอย่างจาก electron-api-demos ควรมีความสำคัญมากกว่าและควรละเว้นตัวอย่างในเอกสารประกอบหลัก

หมายเหตุ #2: หลายๆ ตัวอย่างในแอปพลิเคชัน Electron-api-demos มีตัวอย่างการสาธิตแบบสดของฟีเจอร์หรือฟังก์ชันการทำงานที่อธิบายไว้ ระบบจะไม่สนใจฟังก์ชันนี้จนกว่าจะผสานรวม Electron Fiddle ในสัปดาห์ที่ 9-10

1. อัปเดตหน้าเว็บที่แสดงรายการฟีเจอร์ทั้งหมดที่พร้อมใช้งาน (ซึ่งสร้างขึ้นในช่วงสัปดาห์ที่ 3) โดยยึดตามลําดับชั้นใหม่ของตัวอย่าง

สัปดาห์ที่ 6 และ 7 จะจัดทำขึ้นเพื่อการโอนตัวอย่างอิเล็กตรอน API ไปยังเอกสารหลักตามเทมเพลตที่อธิบายไว้ข้างต้น ขั้นตอนสุดท้ายคือควรลบหรือเลิกใช้งานที่เก็บ electron-api-demos

สัปดาห์ที่ 8-10

สัปดาห์ที่ 8 จะเน้นที่การเตรียมเทมเพลต (วิธี) ในการผสานรวม Electron Fiddle เข้ากับเอกสารประกอบหลัก โครงการริเริ่มนี้เปิดตัวไปแล้ว (ดูรายละเอียดในข้อบกพร่อง #20442) โดยทีม Electron และอาสาสมัครชุมชน แต่ต้องดำเนินการให้เสร็จสมบูรณ์

หากต้องการดําเนินการต่อกับตัวอย่าง Fiddle เทมเพลตพื้นฐานอาจมีลักษณะดังนี้ 1. เลือกตัวอย่างจากเอกสารประกอบหลัก (เช่น คู่มือเริ่มต้นใช้งาน) ณ จุดนี้ เอกสารควรมีตัวอย่าง Electron-api-demos ด้วย 2. สร้างตัวอย่างขึ้นมาใหม่ใน Electron Fiddle (โดยใช้โค้ดตัวอย่างหรือซอร์สโค้ดเป็นจุดเริ่มต้น) 3. บันทึก Fiddle ไว้ในโฟลเดอร์ในเครื่อง 4. ย้ายตัวอย่างไปยัง /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO] * รายการตัวอย่างที่เสร็จสมบูรณ์จะอธิบายไว้ในส่วน "รายการเดโม" ของปัญหา 5. เพิ่มปุ่ม "เปิดใน Fiddle" ตามที่อธิบายไว้ในความคิดเห็นแรกในข้อบกพร่อง #2848

สัปดาห์ที่ 9 และ 10 จะเน้นไปที่การผสานรวมตัวอย่างใน electron-api-demos (ซึ่งแปลงเป็น Fiddle ไว้แล้ว) เข้ากับเอกสารประกอบหลักตามเทมเพลตที่อธิบายไว้ข้างต้น

สัปดาห์ที่ 11

สัปดาห์นี้เราจะทุ่มเทอย่างเต็มที่เพื่อทำให้โปรเจ็กต์การเขียนเสร็จสมบูรณ์หลังจากย้ายข้อมูลรีโพซิทอรี electron-api-demos และตัวอย่าง Electron Fiddle เรียบร้อยแล้ว ซึ่งรวมถึงการตรวจสอบต่อไปนี้ - ตรวจสอบว่าตัวอย่างโค้ดที่มีอยู่ทั้งหมดมีปุ่ม "เปิดใน Fiddle" - ตรวจสอบว่าตัวอย่างโค้ดที่มีอยู่ทั้งหมดทํางานเป็น Fiddle ได้อย่างถูกต้อง - ตรวจสอบว่าเอกสารประกอบหลักไม่ได้อ้างอิงถึงที่เก็บ electron-api-demos อีกต่อไป

สัปดาห์ที่ 12

สรุปงานที่ทำเสร็จแล้ว การตรวจสอบการยอมรับ