หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- moja ทั่วโลก
- ผู้เขียนด้านเทคนิค:
- Tlazypanda
- ชื่อโปรเจ็กต์:
- เอกสารประกอบคู่มือการเริ่มต้นใช้งานด้านเทคนิคสำหรับ 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 ได้ เอกสารปัจจุบันยังเน้นการตั้งค่าที่เรียงลำดับในไฟล์ Docker และข้อมูลที่เพียงพอเกี่ยวกับวิธีสร้างจาก Makefile ด้วย - FLINT.ตัวอย่าง: เอกสารประกอบปัจจุบันไม่ได้ให้วัตถุประสงค์ในการตั้งค่าที่เก็บนี้ ซึ่งจะให้ตัวอย่างวิธีใช้ FLINT คุณสามารถแยกการเรียกใช้ตัวอย่างที่แตกต่างกันได้ดีขึ้น โดยใช้คำสั่งเฉพาะในการดำเนินการ นอกจากนี้ เรายังต้องลิงก์ที่เก็บนี้กับที่เก็บของ FLINT หลักของเราด้วย ซึ่งจะให้ผู้ใช้มีวิธีไปยังส่วนต่างๆ ที่นี่เพื่อดูตัวอย่างการใช้งานจริง
โดยจำเป็นต้องเพิ่มข้อมูลต่อไปนี้ลงในเอกสารประกอบปัจจุบัน - การใช้งาน Git และ GitHub: ข้อมูลนี้จะแสดงวิธีการทีละขั้นตอนเกี่ยวกับวิธีแยก โคลน แล้วตั้งค่าอัปสตรีมระยะไกลสำหรับที่เก็บ นอกจากนี้ยังมีข้อมูลเกี่ยวกับวิธีทำฐานข้อมูลใหม่เทียบกับต้นฉบับล่าสุดและวิธีจัดการกับความขัดแย้งในการผสานอีกด้วย - ป้ายและอีโมจิ: เอกสารปัจจุบันยังไม่มีป้ายและอีโมจิ ซึ่งจะช่วยให้ผู้มีส่วนร่วมรายใหม่รู้สึกเหมือนได้รับการต้อนรับและพบปัญหาที่น่ากังวลน้อยลง - ข้อมูลเกี่ยวกับปัญหาการจับเวลาครั้งแรก/ผู้เริ่มต้นเอง: ข้อมูลนี้จะช่วยนำผู้มีส่วนร่วมรายใหม่ไปยังปัญหาสำหรับผู้เริ่มต้นและเว็บไซต์ของชุมชน - ข้อมูลเกี่ยวกับที่เก็บ Import-me: ที่เก็บ Import-me จะทำหน้าที่เป็นเทมเพลตพื้นฐานสำหรับการเริ่มต้นที่เก็บ Moja Global เอกสารปัจจุบันไม่ได้พูดถึงความสำคัญดังกล่าว ซึ่งจำเป็นต้องอัปเดตเพื่อพูดถึงที่เก็บ Import-me และจำเป็นต้องเพิ่มขั้นตอนการเลือกเป็นเทมเพลตในการสร้างที่เก็บใหม่ด้วย นอกจากนี้ควรมีกระบวนการที่สร้างขึ้นเพื่อให้นักเขียนโค้ดแนะนำคุณลักษณะเพิ่มเติมสำหรับที่เก็บ 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 เพื่อแก้ไขคำถามและอภิปรายเพิ่มเติมเกี่ยวกับโครงการ