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