หน้านี้มีรายละเอียดของโครงการเขียนเชิงเทคนิคที่ยอมรับใน Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- ScummVM
- ผู้เขียนด้านเทคนิค:
- b-gent
- ชื่อโปรเจ็กต์:
- ปรับปรุงเอกสารประกอบเกี่ยวกับซอร์สโค้ดผ่าน Doxygen
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
มีการเผยแพร่เอกสารประกอบปัจจุบันของ ScummVM API (ซอร์สโค้ด) ที่ https://doxygen.scummvm.org/modules.html
แต่น่าเสียดายที่เราไม่พบช่องในด้านต่างๆ ต่อไปนี้
1) ระบบแทบไม่มีโครงสร้างเลย ข้อมูลทั้งหมดลอยอยู่ในระดับเดียวกัน
2) องค์ประกอบ C++ ถูกบันทึกไว้โดยไม่สอดคล้องกับบางส่วนที่ไม่มีการบันทึกเลย นี่เป็นเรื่องที่องค์กรกล่าวถึงว่าเป็นปัญหาหลักอย่างหนึ่ง
3) ระบบยังคงแสดงเนื้อหาที่ล้าสมัยและเลิกใช้งานแล้วในเอาต์พุต
4) ภาษาและการใช้การติดแท็กออกซิเจนควรสอดคล้องกันมากขึ้น จำเป็นต้องมีชุดของกฎสำหรับขั้นตอนนี้ ซึ่งเป็นสิ่งที่อาจจะใช้เป็นพื้นฐานสำหรับคู่มือรูปแบบเอกสารประกอบในอนาคตสำหรับโครงการนี้ได้
5) ปรับปรุง CSS doxygen ที่ใช้ในหน้านี้ให้คล้ายกับเว็บไซต์ ScummVM มากขึ้นที่ https://www.scummvm.org
ปัญหาทั้งหมดนี้สามารถจัดการได้ในระหว่างโครงการซีซันของเอกสาร
ใบสมัครเข้าร่วมซีซันของเอกสารในซีซันนี้มาพร้อมกับฉบับร่างประชาสัมพันธ์ที่เราได้เปิดในโครงการเพื่อแสดงการปรับปรุงที่เป็นไปได้บางอย่างซึ่งเราขอเสนอที่ https://github.com/scummvm/scummvm/pull/2361 ดูรายละเอียดบางส่วนเกี่ยวกับสิ่งที่มีในสไลด์และดูความแตกต่าง
การประชาสัมพันธ์เกี่ยวข้องกับเรื่องนี้คร่าวๆ:
1) ฉันคิดว่าสิ่งที่น่าสับสนที่สุดในตอนนี้สำหรับผู้มีโอกาสเป็นผู้สนับสนุนรายใหม่ และโดยทั่วไปแล้วทุกคนที่ดูเอกสารเกี่ยวกับ API ฉบับปัจจุบันก็คือการขาดโครงสร้าง การเปิดตัวเอกสารประกอบของ API ที่มีโครงสร้างจะช่วยเพิ่มความสะดวกในการอ่าน ความค้นหาง่าย และช่วยให้ชุดเอกสารมีประสิทธิภาพยิ่งขึ้น นั่นคือเหตุผลที่ PR แนะนำกลุ่ม Doxygen ให้กับไฟล์ส่วนหัวทั้งหมดในโฟลเดอร์ "common" ในโครงสร้างใหม่นี้ ถ้ามีคนต้องการหาเอกสารสำหรับ API ที่เกี่ยวข้องกับระบบปฏิบัติการ (เช่น) ก็สามารถค้นหาได้ง่ายในการนำทาง
2) สร้างไฟล์การกำหนดค่า Doxygen ใหม่เพื่อให้สร้างเอกสารนี้ได้
3) ไฟล์ 'links.doxyfile' ซึ่งลิงก์ทั้งหมดที่ใช้ทั่วทั้งชุดเอกสารสามารถใช้แหล่งข้อมูลเดียวได้ กลไกที่มีประโยชน์เมื่อทำงานกับ Doxygen
4) CSS doxygen ที่แก้ไข ข้อมูลนี้มาจากโปรเจ็กต์โอเพนซอร์สอื่นและเป็นเพียงจุดเริ่มต้นเท่านั้น รูปลักษณ์และความรู้สึกของหน้า Doxygen ควรสอดคล้องกับหน้าเว็บ ScummVM มากกว่าหรือน้อยลง
สิ่งที่ฝ่ายประชาสัมพันธ์ไม่ได้กล่าวถึงแต่สิ่งที่จำเป็นต้องปรับปรุงก็คือตัวเนื้อหาเอง ในที่นี้หมายถึงการระบุส่วนสำคัญของโค้ดที่ไม่ได้จัดทำเป็นเอกสาร ส่วนที่ไม่มีเอกสารประกอบเพียงพอ หรือส่วนโค้ดที่ล้าสมัยซึ่งควรนำออกจากเอกสาร เนื่องจากฉันไม่เคยทำงานโครงการนี้มาก่อน จึงต้องได้รับคำแนะนำจากที่ปรึกษาเพื่อให้บรรลุเป้าหมายนี้
แน่นอนว่าการที่เราจะใช้ทุกอย่างจากฝ่ายประชาสัมพันธ์จะขึ้นอยู่กับการหารือกับองค์กรด้วย ผมคิดว่าการกระทำนั้นสำคัญกว่าคำพูด ฉันจึงตัดสินใจแสดงสิ่งที่ทำได้แทนการอธิบายในใบสมัคร
การเปลี่ยนแปลงเดียวที่ฉันจะเสนอก็คือเริ่มจากการทำโครงสร้าง ดังที่ได้กล่าวไปแล้ว ซึ่งสามารถทำได้ในสัปดาห์ที่ 1 และ 2 ร่วมกับการสร้างออกซิเจน (ซึ่งส่วนใหญ่ทำไปแล้ว) และฟื้นฟูผิวด้วย Doxygen หลังจากนั้น ฉันเห็นว่าวิธีที่ดีที่สุดคือการศึกษาส่วนต่างๆ ทีละส่วนกับที่ปรึกษาเพื่อระบุปัญหาและปรับปรุงเอกสารออกซิเจน
ฉันเห็นโครงการนี้เป็นโครงการที่มีความยาวมาตรฐาน แต่แน่ใจว่ามีการปรับปรุงอื่นๆ ที่เกี่ยวข้องกับเอกสาร API ที่สามารถทำได้หลังจากโครงการ GSoD เสร็จสิ้น ตัวอย่างเช่น การหาคู่มือสไตล์เอกสารประกอบและเพิ่มลงใน Wiki เพื่อให้ผู้มีส่วนร่วมทราบว่าควรบันทึกรหัสที่ตนเพิ่มไว้อย่างไร
เรายินดีให้ความช่วยเหลือในการทำงานเช่นนี้หลังจาก GSoD สิ้นสุดแล้ว ฉันมั่นใจว่า ScummVM สามารถใช้ผู้เขียนด้านเทคนิคที่จะช่วยให้เอกสาร API ของ ScummVM มีคุณภาพและใช้งานได้ดี ฉันยังเห็นว่ามีโปรเจ็กต์เอกสารอื่นๆ ในอนาคตที่เราช่วยคุณได้ เช่น การสร้างคู่มือเกี่ยวกับวิธีทำงานกับปลั๊กอิน