หน้านี้มีรายละเอียดของโครงการเขียนเชิงเทคนิคที่ยอมรับใน 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/ นี่เป็นตัวอย่างที่ฉันสร้างขึ้นสำหรับข้อเสนอนี้)
จากการตรวจสอบและการวิเคราะห์ในขั้นตอนก่อนหน้า สร้างโครงกระดูกที่ตรงไปตรงมาของโครงสร้าง / ดัชนีเอกสาร GenPipes ที่เสนอ แล้วนำไปวางในเว็บไซต์ RTD
- ซึ่งเกี่ยวข้องกับการสร้างที่เก็บ GitHub (เช่น ใช้เครื่องมือ Sphinx) และไฟล์เอกสารพื้นฐาน
- นอกจากนี้ยังรวมถึงการสร้าง TOC ใหม่ที่คำนึงถึงทั้งผู้ใช้ใหม่และการใช้งานที่มีประสบการณ์สำหรับส่วน / กระแสข้อมูลต่างๆ
ตรวจสอบ / รับการอนุมัติ TOC โครงกระดูกอ่อน
ระหว่างขั้นตอนการประเมิน GenPipes GSoD ฉันพยายามสร้างคุณค่าให้กับ GenPipes ผ่านตัวอย่างนี้ที่โฮสต์ที่ RTD โปรดทราบว่าข้อมูลนี้มีไว้เพื่อวัตถุประสงค์ในการสาธิตเท่านั้น เป็นลิงก์ที่มีการป้องกันยังไม่แสดงต่อสาธารณะบน RTD เดโมนี้สามารถใช้เพื่อเริ่มความพยายาม RTD ของ GenPipes โดยไม่คำนึงว่าจะได้รับเลือกไหม ฉันได้ตรวจสอบแหล่งที่มาในที่เก็บ 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 หากจำเป็น ให้สร้างเอกสารใหม่หากทำได้ และนำสิ่งที่เป็นไปได้ / เกี่ยวข้องมาใช้ซ้ำ
- นำเข้าเอกสารเริ่มต้นนี้ที่ตั้งค่าเป็น ReadTheDocuments เป็น Proof of Concept โดยจัดเก็บเป็นที่เก็บเอกสารที่มีการป้องกัน จดบันทึกล่วงหน้าเพื่อแนะนำให้ผู้ใช้ใหม่ไปที่เอกสารต้นฉบับของ GenPipes จนกว่าจะมีการตรวจสอบ/เปลี่ยนเวอร์ชันอย่างเป็นทางการ
รีวิว/แก้ไขหลักสูตร/อัปเดต
ขั้นตอนที่ 3: ปรับแต่ง ตรวจสอบ และเผยแพร่ฉบับร่างแรกที่ RTD
กรอกรายละเอียดของโครงสร้างเอกสารใหม่ของ GenPipes ที่เสนอลงใน GenPipes TOC – เพิ่มเอกสารอื่นๆ นอกเหนือจากเอกสารฉบับแรก (GenPipes Readme), แนวคิด, บทแนะนำ ฯลฯ
เพิ่มการแบ่งเขตที่ชัดเจนใน TOC เพื่อระบุผู้ใช้ใหม่, ผู้ใช้ GenPipes ที่มีประสบการณ์, นักพัฒนาซอฟต์แวร์ GenPipes ฯลฯ
เสนอแนะให้พูดคุยเกี่ยวกับกระบวนการทำงานด้วยระบบอัตโนมัติบางส่วนผ่าน RTD (sphinx Builds) เกี่ยวกับวิธีการบำรุงรักษา แก้ไขโดยผู้ใช้ GenPipes และกรณีที่ C3G จะอนุญาตสำหรับผู้ให้ข้อมูลเอกสารภายนอก การดำเนินการนี้อาจต้องมีหลักเกณฑ์บางอย่างในการอัปเดตเอกสารซึ่งคล้ายกับหลักเกณฑ์การเขียนโค้ด อาจต้องใช้ขั้นตอนย่อยเพิ่มเติม ตัวอย่างเช่น ให้ตรวจตัวสะกดโดยอัตโนมัติก่อนการอนุมัติ PR ในเอกสาร GenPipes
รายงาน
สุดท้าย ให้สร้างรายงานสำหรับ GSoD โดยอิงตามประสบการณ์ บันทึก และความคิดเห็นจาก Mentor
ความคิดอื่นๆ
ในอนาคต (มากกว่า 3 เดือน) เราจะช่วยดูแล GenPipes ในระยะยาวได้ (หากมี) หรือฝึกอบรมบุคคลอื่นๆ ในกรณีที่จำเป็น เราทราบเรื่องนี้โดยอิงจากผลลัพธ์ของ 3 เดือนแรกนี้
นอกจากนี้ เราขอแนะนำแนวคิดข้อเสนอโครงการเพิ่มเติม ซึ่งก็คือการสร้างบรีฟหน้า GenPipes 3 ที่จะช่วยให้เริ่มต้นใช้งานได้ง่าย ในปัจจุบัน ผู้ใช้ใหม่ต้องพยายามมากมายก่อนจะเริ่มใช้ GenPipes เพราะเอกสารประกอบนั้นดีแต่มีข้อมูลกระจัดกระจายและไม่เอื้อต่อผู้ใช้ใหม่ ไม่แน่ใจว่าคุณจะทำเรื่องนี้ได้ภายใน 3 เดือน แต่เราอยากให้คุณลองใช้งาน
คุณยังสามารถดูข้อเสนอเดียวกันนี้และที่มาของ (ประวัติ) ได้ที่ https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing