หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- ScummVM
- นักเขียนเชิงเทคนิค
- B-Gent
- ชื่อโปรเจ็กต์:
- ปรับปรุงเอกสารประกอบซอร์สโค้ดผ่าน Doxygen
- ความยาวของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
เอกสาร ScummVM API (ซอร์สโค้ด) ปัจจุบันมีการเผยแพร่ที่นี่: https://doxygen.scummvm.org/modules.html
แต่ก็ยังขาดแคลนในหลายด้าน ดังนี้
1) แทบจะไม่มีโครงสร้างเลย ข้อมูลทั้งหมดอยู่ในระดับเดียวกัน
2) องค์ประกอบ C++ มีเอกสารประกอบที่ไม่สอดคล้องกัน โดยไม่มีเอกสารประกอบสำหรับองค์ประกอบบางรายการเลย องค์กรกล่าวถึงเรื่องนี้ว่าเป็นหนึ่งในปัญหาหลัก
3) เนื้อหาที่ล้าสมัยและเลิกใช้งานแล้วยังคงแสดงอยู่ในเอาต์พุต
4) ภาษาและการใช้การติดแท็ก doxygen ควรมีความสอดคล้องกันมากขึ้น คุณจำเป็นต้องมีชุดกฎสำหรับสิ่งนี้ ซึ่งสามารถนำมาใช้เป็นฐานสำหรับการจัดเอกสารในอนาคตของโปรเจ็กต์นี้ได้
5) CSS ของ doxygen ที่ใช้ในหน้านี้ควรได้รับการปรับปรุงให้คล้ายกับเว็บไซต์ ScummVM มากขึ้น https://www.scummvm.org
ปัญหาเหล่านี้ทั้งหมดสามารถแก้ไขได้ในระหว่างโปรเจ็กต์ Season of Docs
การสมัครเข้าร่วมกิจกรรม Season of Docs ครั้งนี้มาพร้อมกับ PR ฉบับร่างที่เราเปิดในโปรเจ็กต์เพื่อสาธิตการปรับปรุงที่เป็นไปได้บางส่วนที่เราเสนอ https://github.com/scummvm/scummvm/pull/2361 ดูรายละเอียดเกี่ยวกับสิ่งที่ PR ฉบับร่างมีให้และดูความแตกต่างได้ที่คำอธิบาย
ตัวอย่างคร่าวๆ ของสิ่งที่ PR เกี่ยวข้องมีดังนี้
1) ฉันคิดว่าสิ่งที่ทำให้คุณสับสนมากที่สุดในขณะนี้สำหรับผู้มีโอกาสเป็นผู้ร่วมให้ข้อมูลรายใหม่ และโดยทั่วไปทุกคนที่ดูเอกสาร API ปัจจุบันก็คือการขาดโครงสร้าง การแนะนำเอกสารประกอบเกี่ยวกับ API ที่มีโครงสร้างจะทำให้ชุดเอกสารอ่านง่ายขึ้น หาพบได้ง่าย และทำให้ชุดเอกสารใช้งานได้ด้วย ด้วยเหตุนี้ PR ของฉันจึงแนะนำกลุ่ม doxygen ให้กับไฟล์ส่วนหัวทั้งหมดในโฟลเดอร์ "common" โครงสร้างใหม่นี้ช่วยให้ผู้ใช้ค้นหาเอกสารสำหรับ API ที่เกี่ยวข้องกับระบบปฏิบัติการ (เช่น) ได้ง่ายในแถบนําทาง
2) มีการสร้างไฟล์การกําหนดค่า doxygen ใหม่เพื่อใช้สร้างเอกสารประกอบนี้
3) ไฟล์ "links.doxyfile" ซึ่งเป็นแหล่งที่มาของลิงก์ทั้งหมดที่ใช้ในชุดเอกสาร กลไกที่มีประโยชน์เมื่อทำงานกับ Doxygen
4) CSS ของ doxygen ที่แก้ไขแล้ว ปัจจุบันนำมาจากโปรเจ็กต์โอเพนซอร์สอื่นและเป็นเพียงจุดเริ่มต้นเท่านั้น รูปลักษณ์ของหน้า Doxygen ควรสอดคล้องกับหน้าเว็บ ScummVM อย่างน้อยที่สุด
สิ่งที่ PR ไม่ได้กล่าวถึงแต่ต้องดำเนินการอย่างแน่ชัดคือเนื้อหา หมายถึงการระบุส่วนสําคัญของโค้ดที่ไม่มีเอกสารประกอบ ส่วนที่เขียนเอกสารประกอบไม่เพียงพอ หรือส่วนโค้ดที่ล้าสมัยซึ่งควรนําออกจากเอกสารประกอบ เนื่องจากฉันไม่เคยทํางานในโปรเจ็กต์นี้มาก่อน จึงจําเป็นต้องได้รับคําแนะนําจากผู้แนะนํา
แน่นอนว่าเราจะนำสิ่งใดจาก PR มาใช้หรือไม่นั้นขึ้นอยู่กับการพูดคุยกับองค์กร แนวคิดของฉันคือการกระทำสำคัญกว่าคำพูด ดังนั้นฉันจึงตัดสินใจแสดงสิ่งที่ทำได้แทนที่จะอธิบายไว้ในใบสมัคร
องค์กรได้ระบุลำดับเวลาคร่าวๆ สำหรับโปรเจ็กต์นี้ดังนี้ สัปดาห์ งานหลัก สัปดาห์ที่ 0 (ก่อนวันที่ 9/14) การพูดคุยและตรวจสอบข้อเสนอ สัปดาห์ที่ 1 (9/14) การตั้งค่าบิลด์ Doxygen สัปดาห์ที่ 2 (9/21) รีเฟรชสกิน Doxygen (สำคัญต่ำ) สัปดาห์ที่ 3 (9/28) โค้ดทั่วไป - OSystem, FS, โครงสร้างข้อมูล, สตริง ฯลฯ สัปดาห์ที่ 4 (10/05) โค้ดทั่วไป - ต่อจากสัปดาห์ที่ 3 สัปดาห์ที่ 5 (10/12) เครื่องมือ - โค้ดทั่วไปและเครื่องมือตัวอย่าง สัปดาห์ที่ 6 (10/19) กราฟิก สัปดาห์ที่ 7 (10/26) เสียง สัปดาห์ที่ 8 (11/02) วิดีโอ รูปภาพ สัปดาห์ที่ 9 (11/09) แบ็กเอนด์ - แพลตฟอร์ม กราฟิก กิจกรรม สัปดาห์ที่ 10 (11/23) แบ็กเอนด์ - ต่อจากสัปดาห์ที่ 9 สัปดาห์ที่ 11 (11/30) สรุปและส่งโปรเจ็กต์
การเปลี่ยนแปลงเดียวที่เราขอแนะนำคือให้เริ่มต้นด้วยการปรับโครงสร้างตามที่ได้กล่าวไปแล้ว ซึ่งทำได้ในสัปดาห์ที่ 1 และ 2 พร้อมกับการตั้งค่าบิลด์ Doxygen (ซึ่งทําเสร็จไปมากแล้ว) และการรีเฟรชสกิน Doxygen หลังจากนั้น เราเห็นด้วยว่าควรตรวจสอบส่วนต่างๆ ทีละส่วนกับที่ปรึกษาเพื่อระบุปัญหาและปรับปรุงเอกสารประกอบ Doxygen
เราเห็นว่านี่เป็นโปรเจ็กต์ที่มีความยาวมาตรฐาน แต่เรามั่นใจว่ายังมีการปรับปรุงอื่นๆ ที่เกี่ยวข้องกับเอกสารประกอบ API ที่ทำได้หลังจากโปรเจ็กต์ GSoD เสร็จสิ้น ตัวอย่างเช่น การคิดรูปแบบคู่มือการเขียนเอกสารประกอบและเพิ่มลงในวิกิเพื่อให้ผู้ร่วมให้ข้อมูลทราบว่าควรบันทึกโค้ดที่ตนกำลังเพิ่มไว้อย่างไร
เรายินดีให้ความช่วยเหลือเกี่ยวกับงานเช่นนี้หลังจาก GSoD สิ้นสุดลง เราเชื่อว่า ScummVM ต้องการนักเขียนเนื้อหาทางเทคนิคที่จะตรวจสอบว่าเอกสาร API มีคุณภาพและใช้งานได้ง่าย เราเห็นว่าคุณมีโปรเจ็กต์เอกสารอื่นๆ ในอนาคตที่เราช่วยคุณได้ เช่น การสร้างคู่มือเกี่ยวกับวิธีใช้ปลั๊กอิน