โปรเจ็กต์ GenPipes

หน้านี้มีรายละเอียดโครงการงานเขียนเชิงเทคนิคที่ได้รับการยอมรับใน Google Season of เอกสาร

สรุปโปรเจ็กต์

องค์กรโอเพนซอร์ส
GenPipes
นักเขียนเชิงเทคนิค
shaloo
ชื่อโปรเจ็กต์:
ตั้งค่าเอกสาร GenPipes ที่ "อ่านเอกสาร"
ความยาวของโปรเจ็กต์:
ระยะเวลามาตรฐาน (3 เดือน)

คำอธิบายโปรเจ็กต์

เรากำลังเสนอแผนแบบ 3 ขั้นตอนเพื่อให้บรรลุวัตถุประสงค์ในการจัดทำเอกสารประกอบของ GenPipes ใน "อ่านเอกสาร"

ขั้นตอนที่ 1: POC

  • ตรวจสอบเอกสารประกอบที่มีอยู่ของ GenPipes ในฐานะผู้ใช้ / นักวิจัยใหม่

    • ระบุข้อมูลที่ขาดหายไป ความไม่ถูกต้อง
    • แนะนำหัวข้อใหม่ในเอกสาร (หากจำเป็น)
    • ร่างแผนที่สถาปัตยกรรมข้อมูลเพื่อเข้าถึงกลุ่มเป้าหมาย โดยเน้นที่ผู้ใช้ใหม่

    (หมายเหตุ: ในระหว่างขั้นตอนนี้ เราอาจต้องการข้อมูลจากที่ปรึกษา GenPipes เกี่ยวกับการตั้งค่าที่เก็บ GitHub ใหม่ซึ่งสามารถโฮสต์เอกสาร GenPipes สำหรับ RTD ได้ คุณสามารถใช้ที่เก็บ GitHub นี้เพื่อนําเข้าเอกสารทั้งหมดในไปป์ไลน์การสร้าง RTD ซึ่งอาจต้องใช้ข้อมูลเชิงลึกเกี่ยวกับกฎของที่เก็บ GenPipes และหลักเกณฑ์การจัดการแหล่งที่มาของเอกสาร หากจำเป็นต้องปฏิบัติตาม หรือจะใช้มาตรฐานก็ได้เท่าที่ทราบ นอกจากนี้ เรายังสาธิตการตั้งค่าตัวอย่างรีโป RTD โดยใช้บัญชี GitHub ของเราได้ เช่น https://gpdocs.readthedocs.io/en/latest/ ซึ่งเป็นตัวอย่างที่เราสร้างมาสำหรับข้อเสนอนี้)

  • จากการตรวจสอบและการวิเคราะห์ในขั้นตอนก่อนหน้า ให้สร้างโครงกระดูกเปล่าของโครงสร้าง / ดัชนี GenPipes Documentation ที่เสนอและใส่ไว้ในเว็บไซต์ RTD

    • ซึ่งเกี่ยวข้องกับการสร้างรีโป GitHub (โดยใช้เครื่องมือ Sphinx เป็นต้น) และไฟล์เอกสารประกอบพื้นฐาน
    • ซึ่งรวมถึงการสร้าง TOC ใหม่โดยคำนึงถึงทั้งผู้ใช้ใหม่และผู้ใช้ที่มีประสบการณ์ในส่วนต่างๆ / ขั้นตอนของข้อมูล

  • ตรวจสอบ / ขออนุมัติ TOC ฉบับร่าง

    ในระหว่างระยะการประเมิน GSoD ของ GenPipes เราพยายามสร้างมูลค่าให้กับ GenPipes ผ่านตัวอย่างนี้ที่โฮสต์ใน RTD โปรดทราบว่าลิงก์นี้มีไว้สําหรับการสาธิตเท่านั้น ลิงก์ที่มีการป้องกันยังไม่ได้แสดงต่อสาธารณะใน RTD ไม่ว่าเราจะติดรอบคัดเลือกหรือไม่ เราสามารถใช้เดโมนี้เพื่อเริ่มต้นความพยายามใน RTD ของ GenPipes ได้ เราได้ตรวจสอบแหล่งที่มาในที่เก็บข้อมูล GitHub ของ c3g/GenPipes แล้ว เมนเทอร์ Rola และ Hector ชอบวิดีโอนี้ระหว่างการสนทนาผ่าน "การแชร์หน้าจอ" ทาง Skype เมื่อก่อนหน้านี้ เราจึงคิดว่าทีม GSoD อาจอยากดูวิดีโอนี้ด้วย ขณะนี้เป็นเพียงโครงร่างคร่าวๆ แต่เราวางแผนที่จะอัปเดตเมื่อถึงเวลาที่เหมาะสมจนถึงวันที่ 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 (Sphinx Builds) เกี่ยวกับวิธีที่ผู้ใช้สามารถดูแลรักษาและแก้ไขชุดเอกสาร GenPipes ได้ และ C3G จะอนุญาตการดำเนินการดังกล่าวสำหรับผู้จัดทำเอกสารภายนอกหรือไม่ ซึ่งอาจต้องมีการสร้างหลักเกณฑ์บางอย่างสำหรับการอัปเดตเอกสาร ซึ่งคล้ายกับหลักเกณฑ์การเขียนโค้ด อาจต้องมีขั้นตอนย่อยเพิ่มเติม เช่น ดำเนินการตรวจตัวสะกดอัตโนมัติก่อนการอนุมัติ PR ในเอกสาร GenPipes

รายงาน

และสุดท้าย ให้สร้างรายงานสำหรับ GSoD โดยอิงจากประสบการณ์ บันทึก และความคิดเห็นจากที่ปรึกษา

ความคิดเห็นอื่นๆ

ในอนาคต (หลังจาก 3 เดือน) หากมี เราจะช่วยดูแล GenPipes ในระยะยาวได้ หรือฝึกอบรมให้คนอื่นๆ เป็นไปในลักษณะเดียวกัน หากจำเป็น เราจะพิจารณาเรื่องนี้ตามผลลัพธ์ของ 3 เดือนแรก

นอกจากนี้ เราขอแนะนำไอเดียในการเสนอโปรเจ็กต์เพิ่มเติมด้วย ซึ่งก็คือการสร้างข้อมูลสรุป GenPipes 3 หน้าที่ช่วยในการเริ่มต้นใช้งานได้ง่าย ปัจจุบัน ผู้ใช้ใหม่ต้องกระโดดหลายครั้งก่อนที่จะเริ่มต้นใช้งาน GenPipes ได้เนื่องจากเอกสารประกอบครบถ้วนแต่กระจัดกระจายและไม่มีประโยชน์ต่อผู้ใช้ใหม่ เราไม่แน่ใจว่าจะทำได้ภายใน 3 เดือนไหม แต่เราอยากลองดู

คุณสามารถดูข้อเสนอเดียวกันนี้และที่มา (ประวัติ) ได้ที่ https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing