หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- CERN-HSF
- นักเขียนเชิงเทคนิค
- John
- ชื่อโปรเจ็กต์:
- CERN-HSF - เอกสารประกอบเกี่ยวกับรูทสำหรับการนำผู้ชมทั่วไปไปใช้งาน, การผูก Python แบบไดนามิก และบทแนะนำ
- ระยะเวลาของโปรเจ็กต์
- ใช้งานนาน (5 เดือน)
คำอธิบายโปรเจ็กต์
CERN-HSF - ROOT Documentation for General Audience Adoption, Dynamic Python Bindings, and Tutorials Mentor: Olivier Couet, Axel Naumann
ข้อมูลสรุป: เอกสารประกอบเป็นสิ่งจําเป็นต่อการใช้งานซอฟต์แวร์อย่างมีประสิทธิภาพและประสบความสําเร็จของผู้ใช้ เอกสารประกอบสําหรับผู้ใช้ที่ชัดเจน ถูกต้อง และครอบคลุมจะช่วยให้ผู้ใช้สามารถใช้ซอฟต์แวร์ได้อย่างคล่องแคล่วเมื่อพยายามบรรลุเป้าหมาย นอกจากนี้ ตัวอย่างและบทแนะนําที่ชัดเจนยังถือเป็นเครื่องมือที่มีประสิทธิภาพซึ่งช่วยให้ผู้ใช้เรียนรู้ได้อย่างรวดเร็ว
เมื่อเราตรวจสอบการใช้ ROOT โดยนักฟิสิกส์ นักวิจัย และนักพัฒนาซอฟต์แวร์ในแวดวงการวิเคราะห์ข้อมูลและการแสดงภาพสำหรับฟิสิกส์ เราพบว่าทุกคนเห็นประโยชน์ของเอกสารประกอบที่อัปเดตและใช้งานง่าย โดยเฉพาะอย่างยิ่ง เนื่องจากซอร์สโค้ดมีขอบเขตกว้างและเติบโตขึ้นเรื่อยๆ ระบบเอกสารจึงได้รับประโยชน์จากการพัฒนาไปพร้อมๆ กันเพื่อให้ผู้ใช้ได้รับประโยชน์สูงสุดจาก ROOT
สรุปและการวิเคราะห์เอกสารปัจจุบัน ปัจจุบันเอกสารสำหรับผู้ใช้มีคำแนะนำที่ช่วยให้นักฟิสิกส์นำ ROOT มาใช้ได้ง่ายขึ้นเมื่อเทียบกับผู้ชมทั่วไป นอกจากนี้ ในบางหัวข้อ เช่น การเชื่อมโยง Python แบบไดนามิก อาจมีการปรับปรุงเพื่อให้ได้เอกสารประกอบที่ครอบคลุมและชัดเจนยิ่งขึ้น ในทํานองเดียวกัน รูปแบบข้อมูล RNTuple ใหม่ก็ไม่มีข้อมูลจำเพาะโดยละเอียดที่จำเป็น สุดท้าย เอกสารประกอบปัจจุบันไม่มีบทแนะนำที่เกี่ยวข้องกับ ROOT 7
วิธีการ: หลังจากปรึกษากับ Olivier ดูเหมือนว่าวิธีแก้ปัญหาข้างต้นควรมุ่งเน้นที่การระบุช่องว่างความรู้ระหว่างนักวิจัยเฉพาะทางกับผู้ชมทั่วไป การสร้างเอกสารประกอบเพื่อเติมเต็มช่องว่างดังกล่าว เขียนเอกสารประกอบที่ละเอียดยิ่งขึ้นเกี่ยวกับ Dynamic Python Bindings การใช้ "บทแนะนำสำหรับการวิเคราะห์สมัยใหม่" สำหรับ ROOT 7 และสร้างข้อกำหนดทางเทคนิคโดยละเอียดสำหรับ RNTuple ด้วยเหตุนี้ ในระหว่างกระบวนการนี้ เอกสารประกอบอาจรวม Jupyter Notebook เพื่อให้เครื่องมือการเรียนรู้ที่จับต้องได้และเป็นแบบอินเทอร์แอกทีฟช่วยผู้ใช้ได้
ลำดับเวลา: เราคาดว่าขั้นตอนของโปรเจ็กต์จะแบ่งออกเป็นดังนี้ ระบุช่องว่างความรู้ระหว่างนักวิจัยเฉพาะทางกับผู้ชมทั่วไป (ขณะอ่านเอกสารประกอบและซอร์สโค้ดปัจจุบัน) → 1-2 สัปดาห์ สร้างและแก้ไขเอกสารประกอบเพื่อเติมเต็มช่องว่างนั้น → 3 สัปดาห์ เขียนเอกสารประกอบที่ละเอียดยิ่งขึ้นเกี่ยวกับ Dynamic Python Bindings → 3 สัปดาห์ ใช้บทแนะนำสำหรับ Dynamic Python Bindings → 3 สัปดาห์ ใช้บทแนะนำสำหรับ ROOT 7 → 4 สัปดาห์ สร้างข้อกำหนดทางเทคนิคโดยละเอียดสำหรับ RNTuple → 3 สัปดาห์ ตรวจสอบว่าวัตถุประสงค์ของโปรเจ็กต์เสร็จสมบูรณ์แล้ว → 1 สัปดาห์
สิ่งที่ส่งมอบและหลักเกณฑ์สู่ความสําเร็จ: เอกสารประกอบสําหรับผู้ใช้แบบรวมศูนย์ฉบับเดียวที่ไม่มีช่องโหว่ เอกสารประกอบสําหรับผู้ใช้ที่อัปเดตอย่างสมบูรณ์เพื่อให้สอดคล้องกับฟีเจอร์ล่าสุด เช่น คลาสที่สืบทอดใหม่ บทแนะนําผ่าน Jupyter Notebook