หน้านี้มีรายละเอียดของโครงการเขียนเชิงเทคนิคที่ยอมรับใน Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- moja ทั่วโลก
- ผู้เขียนด้านเทคนิค:
- ตลาซิแพนด้า
- ชื่อโปรเจ็กต์:
- เอกสารประกอบในคู่มือการเริ่มต้นใช้งานด้านเทคนิคสำหรับ FLINT
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
เอกสารประกอบในคู่มือการเริ่มต้นใช้งานด้านเทคนิคสำหรับ FLINT สำหรับแนะนำผู้ร่วมให้ข้อมูลรายใหม่ผ่านการเริ่มต้นใช้งานทางเทคนิค เพื่อให้ผู้ร่วมให้ข้อมูลรายใหม่สามารถเริ่มต้นใช้งานโดยรับการสนับสนุนขั้นต่ำจากผู้บำรุงรักษาได้อย่างง่ายดาย
ปัญหาเกี่ยวกับโปรเจ็กต์
รายการต่อไปนี้คือรายการปัญหาที่สำคัญที่สุดที่เกี่ยวข้องกับเอกสารปัจจุบัน - วิธีในคู่มือการตั้งค่าในเครื่องที่ไม่เป็นระเบียบ ซึ่งทำให้ผู้มีส่วนร่วมใหม่เริ่มต้นใช้งานได้ยาก - ที่เก็บของ FLINT หลายแห่งไม่มีเอกสารประกอบเกี่ยวกับวัตถุประสงค์และไม่ได้ลิงก์กัน ทำให้ผู้ใช้ใหม่ระบุว่าติดตั้งที่เก็บใดได้ยาก - มีการบันทึกการติดตั้ง Windows ไว้อย่างดี แต่เอกสารประกอบการติดตั้งที่ใช้ Linux ยังมีพื้นที่สำหรับการปรับปรุง - ขณะนี้เวิร์กโฟลว์ Git ยังไม่เป็นส่วนหนึ่งของเอกสารประกอบ
โซลูชันที่เสนอ
ข้อเสนอนี้นำเสนอโซลูชันสำหรับแนะนำผู้ร่วมให้ข้อมูลรายใหม่ในการเริ่มต้นใช้งานทางเทคนิค เพื่อให้ผู้ร่วมให้ข้อมูลรายใหม่สามารถเริ่มต้นใช้งานได้อย่างง่ายดายด้วยการสนับสนุนขั้นต่ำจากผู้บำรุงรักษา ซึ่งสามารถทำได้โดยการเปลี่ยนโครงสร้างภายในเอกสารปัจจุบันใหม่เพื่อทำให้เหมาะสำหรับผู้เริ่มต้น และยังใช้ที่เก็บส่วนกลางแบบสแตนด์อโลนสำหรับเอกสารทั้งหมดที่มี โครงการจะแบ่งออกเป็น 3 ระยะ ดังนี้- - ตรวจสอบเอกสารที่มีอยู่และการเปลี่ยนโครงสร้างภายใน: เป้าหมายของระยะนี้คือการทบทวนคู่มือปัจจุบันและปรับเปลี่ยนโครงสร้างให้กระชับและเข้าใจง่ายสำหรับผู้ร่วมให้ข้อมูลรายใหม่ นอกจากนี้ คุณยังต้องแก้ไขเอกสารประกอบเพื่อให้อ่านง่ายยิ่งขึ้นสำหรับผู้เริ่มต้นโดยเพิ่มป้าย อีโมจิ และข้อมูลเกี่ยวกับปัญหาที่ติดป้ายกำกับด้วยแท็ก "เฉพาะครั้งแรก" หรือ "แท็กปัญหาแรกที่ดี" - สร้างที่เก็บเอกสารแบบสแตนด์อโลนส่วนกลาง: เป้าหมายของระยะนี้คือลิงก์เอกสารทั้งหมดที่มีตามลำดับเชิงตรรกะในที่เก็บแบบสแตนด์อโลน ซึ่งเกี่ยวข้องกับการจัดลำดับหลักเกณฑ์การสนับสนุน คำแนะนำในการตั้งค่าโครงการ และคำแนะนำทีละขั้นตอน - เพิ่มเวิร์กโฟลว์ของนักพัฒนาซอฟต์แวร์และเว็บไซต์ชุมชนสำหรับนักพัฒนาซอฟต์แวร์ใหม่: เป้าหมายในขั้นนี้คือการเพิ่มเวิร์กโฟลว์ของนักพัฒนาซอฟต์แวร์ซึ่งประกอบด้วยหลักเกณฑ์การร่วมให้คำบรรยายของ Git และสถาปัตยกรรมเทคโนโลยีของโครงการ พร้อมด้วยหลักเกณฑ์การทดสอบและ QA เว็บไซต์ชุมชนที่เสนอจะเป็นแอปพลิเคชันหน้าเว็บเดียวที่แสดงขั้นตอนการทำงาน ปัญหาครั้งแรกที่สามารถอ้างสิทธิ์โดยผู้ร่วมให้ข้อมูลรายใหม่และรายชื่อผู้สนับสนุนทั้งหมด ระยะที่ 1: ตรวจสอบเอกสารที่มีอยู่และการเปลี่ยนโครงสร้างภายในโค้ด:
แก้ไขเอกสารประกอบปัจจุบันของที่เก็บต่อไปนี้ - FLINT: เอกสารปัจจุบันไม่ได้มีรายละเอียดมากนักและไม่ได้ให้ลำดับที่เรียงตามลำดับของไลบรารีที่จำเป็นก่อน คู่มือการสอนแบบทีละขั้นตอนจะแบ่งออกเป็นไฟล์ PDF ที่ต่างกัน แต่สามารถรวมไว้ในที่เดียวได้โดยกระชับมากขึ้น นอกจากนี้ คำแนะนำในการติดตั้งยังเหมาะสำหรับหน้าต่าง แต่การติดตั้ง Linux ที่เปลี่ยนเส้นทางไปยังที่เก็บ FLINT.docker อาจเป็นประโยชน์ - FLINT.docker: เอกสารปัจจุบันไม่ได้ให้วัตถุประสงค์ในการตั้งค่าที่เก็บนี้ ซึ่งได้แก่ การติดตั้ง FLINT ของ Linux ผ่าน Docker การสนับสนุนผ่าน Docker จะจำกัดอยู่ที่ Ubuntu 18.04 (Bionic Beaver) เท่านั้น แต่คุณสามารถขยายไปยังรุ่นอื่นๆ ที่ใช้ Linux ได้ เอกสารปัจจุบันยังเน้นอธิบายวิธีตั้งค่าไฟล์ Dockerfile ตามลำดับ และข้อมูลที่เพียงพอเกี่ยวกับวิธีสร้างจาก Makefile - FLINT.example: เอกสารปัจจุบันไม่ได้ให้วัตถุประสงค์ในการตั้งค่าที่เก็บนี้ ทั้งนี้เพื่อให้ตัวอย่างวิธีใช้ FLINT การเรียกใช้ตัวอย่างที่แตกต่างกันสามารถแยกได้ดียิ่งขึ้นโดยมีคำแนะนำเฉพาะในการเรียกใช้ นอกจากนี้ เราจำเป็นต้องลิงก์ที่เก็บนี้กับที่เก็บหลักของ FLINT ของเราเพื่อให้ผู้ใช้สามารถไปยังส่วนต่างๆ ของตำแหน่งนี้เพื่อจะได้ดูตัวอย่างในการใช้งานจริง
โดยจำเป็นต้องเพิ่มข้อมูลต่อไปนี้ลงในเอกสารประกอบปัจจุบัน - การใช้งาน Git และ GitHub: ข้อมูลนี้จะแสดงวิธีการแบบทีละขั้นตอนเกี่ยวกับวิธีแยก โคลน แล้วตั้งค่าอัปสตรีมระยะไกลสำหรับที่เก็บ นอกจากนี้ยังมีข้อมูลเกี่ยวกับวิธีทำฐานข้อมูลใหม่เทียบกับต้นแบบล่าสุดและจัดการความขัดแย้งในการผสานอีกด้วย - ป้ายและอีโมจิ: เอกสารปัจจุบันยังไม่มีป้ายและอีโมจิซึ่งจะช่วยให้ผู้ร่วมเขียนข้อความใหม่รู้สึกถึงการต้อนรับและปัญหาที่น่ากังวลน้อยลง - ข้อมูลเกี่ยวกับปัญหาเกี่ยวกับตัวจับเวลาครั้งแรก/ปัญหาสำหรับผู้เริ่มต้น: ข้อมูลนี้จะช่วยเปลี่ยนเส้นทางผู้มีส่วนร่วมรายใหม่ไปยังปัญหาระดับเริ่มต้นและเว็บไซต์ของชุมชน - ข้อมูลเกี่ยวกับที่เก็บ Import-me: ที่เก็บ Import-me จะทำหน้าที่เป็นเทมเพลตพื้นฐานสำหรับการเริ่มต้นที่เก็บ Moja Global ใดๆ เอกสารประกอบปัจจุบันไม่ได้พูดถึงความสำคัญในเรื่องเดียวกัน จำเป็นต้องอัปเดตเพื่อระบุที่เก็บ Import-me และจำเป็นต้องเพิ่มขั้นตอนการเลือกสิ่งนี้เป็นเทมเพลตในการสร้างที่เก็บใหม่ด้วย นอกจากนี้ ยังควรมีกระบวนการที่กำหนดไว้สำหรับนักเขียนโค้ดเพื่อแนะนำคุณลักษณะเพิ่มเติมสำหรับที่เก็บ Import-me ด้วย
ระยะ 2: สร้างที่เก็บเอกสารแบบสแตนด์อโลนส่วนกลาง :
เครื่องมือที่ใช้สำหรับแพลตฟอร์มโฮสติ้ง:
เครื่องมือที่เสนอสำหรับแพลตฟอร์มโฮสติ้งนี้คือ "อ่านเอกสาร" เนื่องจากเหตุผลต่อไปนี้ - อยู่ในอันดับสูงจากแพลตฟอร์มโฮสติ้งอื่นๆ - การอัปเดตอัตโนมัติสำหรับการพุชคอมมิต - สามารถตั้งค่าและความช่วยเหลือในการแก้ปัญหาได้ง่ายๆ เนื่องจากชุมชนขนาดใหญ่ที่ใช้ระบบนี้ - เอกสารจะจัดรูปแบบโดยใช้ reStructuredText และผลลัพธ์จะรวบรวมโดย Sphinx
จัดระเบียบเนื้อหาทั้งหมดตามลำดับที่สมเหตุสมผล ดังนี้
ลำดับเนื้อหาที่เสนอมีดังนี้ - ข้อมูลเบื้องต้นเกี่ยวกับเอกสารสำหรับนักพัฒนาซอฟต์แวร์: ส่วนนี้จะครอบคลุมข้อมูลเบื้องต้นเกี่ยวกับ Moja Global และ FLINT - การมีส่วนร่วม: ส่วนนี้ประกอบด้วยส่วนย่อย "วิธีให้การสนับสนุน" (ในเรื่องของโค้ด/การรายงานข้อบกพร่อง/การแปล/เอกสารประกอบ/การจัดการเหตุการณ์ ฯลฯ) และ "หลักจรรยาบรรณ" - การตั้งค่าการพัฒนา: ส่วนนี้ประกอบด้วยส่วนย่อย "Git & GitHub เวิร์กโฟลว์" "การติดตั้ง Windows" "การติดตั้ง Windows พร้อม" เป็นเวิร์กโฟลว์สำหรับนักพัฒนาแอป ส่วนนี้จะประกอบไปด้วยการพูดคุยเรื่องเครื่องมือและการทดสอบที่นำมาผสานรวม ส่วนนี้จะพูดถึงวิธีการนำเครื่องมือและการทดสอบแบบผสานรวมในส่วน "การติดตั้ง Windows" มาพูดถึง - เข้าร่วมกับเรา: ส่วนนี้จะมีฟอรัมโซเชียลต่างๆ เช่น ช่อง Slack เพื่อพูดคุยและทำงานร่วมกับ Moja Global
ขั้นตอนที่ 3: เพิ่มเวิร์กโฟลว์ของนักพัฒนาซอฟต์แวร์และเว็บไซต์ชุมชนสำหรับผู้ร่วมให้ข้อมูลรายใหม่
เอกสารเวิร์กโฟลว์ของนักพัฒนาซอฟต์แวร์:
เอกสารประกอบเกี่ยวกับเวิร์กโฟลว์ของนักพัฒนาซอฟต์แวร์จะประกอบด้วยส่วนย่อยต่อไปนี้
- กลุ่มเทคโนโลยี/สถาปัตยกรรมที่ใช้และโมดูลต่างๆ ในโค้ด: เอกสารเพื่อสร้างความคุ้นเคยกับผู้ร่วมให้ข้อมูลใหม่เกี่ยวกับกลุ่มเทคโนโลยีที่นำมาใช้งาน ไลบรารีและโมดูลต่างๆ ของฐานของโค้ด
- เครื่องมือทดสอบและการครอบคลุมแบบผสานรวม: แนะนำผู้ร่วมให้ข้อมูลรายใหม่เกี่ยวกับเครื่องมือไปป์ไลน์ CI/CD ที่ใช้สำหรับการทดสอบ บ็อตที่ครอบคลุม และการตรวจสอบคุณภาพอัตโนมัติที่ทำงานกับโค้ดของตน รวมถึงให้แนวทางแก่พวกเขาว่าควรดำเนินการอย่างไรหากการทดสอบล้มเหลว
- บ็อตที่ใช้เพื่อทำให้เวิร์กโฟลว์ง่ายขึ้น เช่น Zulipbot: การออกแบบเทมเพลตเนื้อหาสำหรับแสดงบ็อต และเอกสารประกอบให้พร้อมใช้งานเพื่อให้ผู้ใช้เข้าใจบ็อต และช่วยปรับปรุงการกำหนดค่าของบ็อตด้วยการร่วมให้ข้อมูล
- การทดสอบและส่งคำขอพุลด้วยตนเอง: เอกสารประกอบเกี่ยวกับวิธีทดสอบคำขอพุลด้วยตนเองกับมาตรฐานที่กำหนด และอัปโหลดผลลัพธ์เป็นภาพหน้าจอ/GIF เมื่อส่งคำขอพุล
- ดึงหลักเกณฑ์การตรวจสอบเพื่อให้ผู้มีส่วนร่วมปฏิบัติตาม: หลักเกณฑ์การติดแท็กบางทีมเพื่อตรวจสอบ และเพิ่มป้ายกํากับ เช่น "ต้องตรวจสอบ" ไปยังการดึงคําขอเพื่อให้ผู้ดูแลตอบกลับได้
เว็บไซต์ของชุมชน:
เว็บไซต์ชุมชนจะมีฟีเจอร์ต่อไปนี้
- ข้อมูลเกี่ยวกับเวิร์กโฟลว์ของเรา: ขั้นตอนการทำงานจะประกอบไปด้วยชุดการดำเนินการที่ผู้มีส่วนร่วมรายใหม่อาจเริ่มต้นด้วย เช่น การอ้างสิทธิ์ในประเด็นการจับเวลาครั้งแรก ตามด้วยการสร้างปัญหาเกี่ยวกับตัวจับเวลาครั้งแรกสำหรับผู้อื่น และช่วยเหลือผู้อื่นโดยการแสดงความคิดเห็นและตรวจสอบคำขอพุล
- รายการปัญหาตัวจับเวลาครั้งแรกเท่านั้น: รายการปัญหาโดยเฉพาะสำหรับผู้ใช้ครั้งแรกหรือผู้ร่วมให้ข้อมูลใหม่
- รายการปัญหาที่ไม่มีการอัปเดต: รายการปัญหาที่ไม่ได้เกิดขึ้นมาเป็นเวลานาน ผู้มีส่วนร่วมจึงช่วยเลือกได้
- รายชื่อผู้ร่วมให้ข้อมูล: รายชื่อผู้ร่วมให้ข้อมูลที่มีส่วนร่วมกับที่เก็บของ Moja Global จนถึงปัจจุบัน
- ผู้ร่วมให้ข้อมูลล่าสุด: รายชื่อผู้ร่วมให้ข้อมูลที่ได้มีส่วนร่วมกับที่เก็บของ Moja Global เมื่อเร็วๆ นี้
- ลิงก์เพื่อเข้าร่วมฟอรัมแชท: ข้อมูลและลิงก์สำหรับเข้าร่วมชุมชน Slack เพื่อแก้ไขคำถามและพูดคุยเพิ่มเติมเกี่ยวกับโครงการ