หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- GenPipes
- ผู้เขียนด้านเทคนิค:
- shaloo
- ชื่อโปรเจ็กต์:
- ตั้งค่าเอกสาร GenPipes ที่ "อ่านเอกสาร"
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ฉันขอเสนอแผนแบบ 3 ขั้นตอนเพื่อให้บรรลุวัตถุประสงค์ในการตั้งค่าเอกสาร GenPipes ใน "อ่านเอกสาร"
ขั้นตอนที่ 1: PoC
ดูเอกสารประกอบที่มีอยู่ของ GenPipes ในฐานะนักวิจัย / ผู้ใช้ใหม่
- ระบุข้อมูลที่ขาดหายไปหรือความไม่ถูกต้อง
- แนะนำหัวข้อเอกสารใหม่ (หากจำเป็น)
- ร่างแผนผังสถาปัตยกรรมข้อมูลเพื่อจัดการกับกลุ่มเป้าหมายโดยเน้นที่ผู้ใช้ใหม่
(หมายเหตุ: ในขั้นตอนนี้ เราอาจต้องการข้อมูลจาก Mentor ของ GenPipes เกี่ยวกับการตั้งค่าที่เก็บ GitHub ใหม่ซึ่งโฮสต์เอกสาร Genpipes สำหรับ RTD ได้ ที่เก็บ GitHub นี้ใช้เพื่อนำเข้าเอกสารทั้งหมดในไปป์ไลน์บิลด์ RTD ได้ อาจจำเป็นต้องมีข้อมูลเชิงลึกเกี่ยวกับกฎที่เก็บ GenPipes และหลักเกณฑ์การจัดการแหล่งที่มาของเอกสาร หากต้องปฏิบัติตาม หรือไม่ก็ใช้มาตรฐานทั่วไปได้นะ นอกจากนี้ สำหรับ PoC เรายังสามารถสาธิตการตั้งค่าที่เก็บ RTD ตัวอย่างโดยใช้บัญชี GitHub ได้ด้วย เช่น https://gpdocs.readthedocs.io/en/latest/ นี่เป็นตัวอย่างที่ฉันสร้างสำหรับข้อเสนอนี้)
จากการตรวจสอบและการวิเคราะห์ในขั้นตอนก่อนหน้า สร้างโครงกระดูก Barebones ของโครงสร้าง / ดัชนีเอกสาร GenPipes ที่เสนอ แล้วนำไปวางในเว็บไซต์ RTD
- ซึ่งเกี่ยวข้องกับการสร้างที่เก็บ GitHub (เช่น การใช้เครื่องมือ Sphinx) และไฟล์เอกสารประกอบพื้นฐาน
- นอกจากนี้ ยังรวมถึงการสร้าง TOC ใหม่โดยคำนึงถึงทั้งผู้ใช้ใหม่และผู้ใช้ตามฤดูกาลสำหรับส่วน / กระแสของข้อมูลต่างๆ
ตรวจสอบ / รับการอนุมัติ TOC สำหรับโครงกระดูกอ่อน
ระหว่างขั้นตอนการประเมิน GenPipes GSoD ฉันพยายามสร้างค่าสำหรับ GenPipes ผ่านตัวอย่างนี้ที่โฮสต์ที่ RTD โปรดทราบว่าข้อมูลนี้มีไว้เพื่อวัตถุประสงค์ในการสาธิตเท่านั้น เป็นลิงก์ที่มีการป้องกัน จึงยังไม่แสดงต่อสาธารณะบน RTD เดโมนี้สามารถใช้เพื่อเริ่มความพยายาม GenPipes RTD ได้ไม่ว่าฉันจะได้รับสิทธิ์หรือไม่ ฉันได้ตรวจสอบแหล่งที่มาในที่เก็บ GitHub c3g/GenPipes แล้ว พี่เลี้ยง Rola และ Hector ชอบวิดีโอนี้ระหว่างการพูดคุยเรื่อง "แชร์หน้าจอ" ของ Skype ก่อนหน้านี้ ผมจึงคิดว่า GSoD Gods ก็อาจอยากเห็นด้วยเช่นกัน ตอนนี้ยังเป็นโครงกระดูกที่เปลือยเปล่าอยู่ แต่ฉันวางแผนที่จะอัปเดตข้อมูลเมื่อมีเวลาจนถึงวันที่ 30 กรกฎาคม
https://genpipes.readthedocs.io/en/latest/
ขั้นตอนที่ 2: การสร้างชุดเอกสาร GenPipes v0.9
ระบุเอกสาร GenPipes ที่มีอยู่หรือปัจจุบันที่สามารถนำเข้า ลิงก์ หรือแปลงเป็นเอกสารที่อิงตาม Sphinx/rst สำหรับการโฮสต์บน RTD โดยพิจารณาไทม์ไลน์ GSoD
หากจำเป็น ให้แปลงเอกสารที่ระบุให้เป็นรูปแบบ RST หากจำเป็น แล้วสร้างเอกสารใหม่หากทำได้ และนำสิ่งที่ทำได้ / เกี่ยวข้องมาใช้ซ้ำ
- นำเข้าเอกสารที่ตั้งค่าเริ่มต้นนี้ไว้ใน ReadTheDocs เป็น Proof of Concept ให้โฮสต์เอกสารเหล่านั้นเป็นที่เก็บที่มีการป้องกัน จดบันทึกล่วงหน้าเพื่อแนะนำให้ผู้ใช้ใหม่ไปที่เอกสารต้นฉบับของ GenPipes จนกว่าจะมีการตรวจสอบ/เปลี่ยนเวอร์ชันอย่างเป็นทางการ
ทบทวน/แก้ไขหลักสูตร/อัปเดต
ขั้นตอนที่ 3: ปรับแต่ง ตรวจสอบ และเผยแพร่ฉบับร่างแรกที่ RTD
กรอกรายละเอียดของโครงสร้างเอกสารใหม่ของ GenPipes ที่เสนอลงใน GenPipes TOC – เพิ่มเอกสารเพิ่มเติมจากเอกสารฉบับแรก (GenPipes Readme), แนวคิด, บทแนะนำ ฯลฯ
เพิ่มการแบ่งส่วนที่ชัดเจนใน TOC เพื่อระบุผู้ใช้ใหม่, ผู้ใช้ GenPipes ที่มีประสบการณ์, นักพัฒนาซอฟต์แวร์ GenPipes ฯลฯ
แนะนําให้พูดคุยเกี่ยวกับกระบวนการทํางานด้วยระบบอัตโนมัติบางส่วนผ่าน RTD (บิลด์สฟิงซ์) เกี่ยวกับวิธีจัดการ แก้ไข ชุดเอกสารของ GenPipes และกรณีที่ C3G จะอนุญาตให้ผู้จัดทำเอกสารภายนอกดำเนินการดังกล่าว ซึ่งอาจต้องสร้างหลักเกณฑ์บางอย่างสําหรับการอัปเดตเอกสารที่คล้ายกับหลักเกณฑ์การเขียนโค้ด อาจมีขั้นตอนย่อยเพิ่มเติม เช่น ให้ตรวจตัวสะกดโดยอัตโนมัติก่อนการอนุมัติ PR ในเอกสาร GenPipes
รายงาน
สุดท้าย ให้สร้างรายงานสำหรับ GSoD โดยอิงตามประสบการณ์ บันทึก และความคิดเห็นจาก Mentor
ความคิดอื่นๆ
ในอนาคต (เกิน 3 เดือน) เราจะช่วยดูแล GenPipes ให้ในระยะยาวได้ (หากมี) หรือฝึกอบรมบุคคลอื่นๆ ในกรณีที่จำเป็น เราตัดสินได้จากผลลัพธ์ของ 3 เดือนแรกนี้
นอกจากนี้ เราจะแนะนำแนวคิดข้อเสนอโครงการเพิ่มเติม ซึ่งก็คือการสร้างบรีฟหน้า GenPipes 3 ที่ช่วยให้เริ่มต้นใช้งานได้อย่างง่ายดาย ทุกวันนี้ ผู้ใช้ใหม่จะต้องดำเนินการข้ามลำดับ จึงจะเริ่มต้นใช้งาน GenPipes ได้ เนื่องจากเอกสารประกอบที่ดีแต่ยังมีข้อมูลไม่มากและไม่เป็นประโยชน์สำหรับผู้ใช้ใหม่ ไม่แน่ใจว่าคุณจะทำเรื่องนี้ได้ภายใน 3 เดือน แต่เราอยากจะลองลองใช้งานดู
คุณยังสามารถดูข้อเสนอเดียวกันนี้และที่มาของข้อเสนอ (ประวัติ) ได้ที่ https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing