หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- ScummVM
- ผู้เขียนด้านเทคนิค:
- b-gent
- ชื่อโปรเจ็กต์:
- ปรับปรุงเอกสารประกอบเกี่ยวกับซอร์สโค้ดผ่าน Doxygen
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
มีการเผยแพร่เอกสารประกอบปัจจุบันเกี่ยวกับ ScummVM API (ซอร์สโค้ด) ที่ https://doxygen.scummvm.org/modules.html
แต่เราขาดเรื่องนี้ในหลายด้าน ได้แก่
1) แทบไม่มีโครงสร้างสำหรับบริการนี้ ข้อมูลทั้งหมดลอยอยู่ในระดับเดียวกัน
2) องค์ประกอบ C++ จะได้รับการจัดทำโดยไม่สอดคล้องกับบางส่วนที่ไม่มีการบันทึกเลย นี่เป็นเรื่องที่องค์กรกล่าวถึงว่าเป็นประเด็นหลักอย่างหนึ่ง
3) ระบบยังคงแสดงเนื้อหาที่ล้าสมัยและเลิกใช้งานแล้วในเอาต์พุต
4) ภาษาและการใช้แท็กด็อกซิเจนควรสอดคล้องกันมากขึ้น คุณจำเป็นต้องมีชุดกฎสำหรับกระบวนการนี้ ซึ่งจะใช้เป็นพื้นฐานสำหรับคู่มือสไตล์เอกสารในอนาคตสำหรับโปรเจ็กต์นี้
5) ปรับปรุง CSS ด็อกซีเจนที่ใช้ในหน้านี้ให้คล้ายกับเว็บไซต์ ScummVM มากขึ้นที่ https://www.scummvm.org
ปัญหาทั้งหมดนี้สามารถจัดการได้ในระหว่างโครงการ Season of Docs
แอปพลิเคชัน ซีซันของเอกสาร นี้มาพร้อมกับร่างประชาสัมพันธ์ที่ผมได้เปิดในโครงการเพื่อสาธิตการปรับปรุงที่เป็นไปได้ ซึ่งผมเสนอ: 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 มากกว่าหรือน้อยลง
สิ่งที่ฝ่ายประชาสัมพันธ์ไม่ได้กล่าวถึงแต่สิ่งที่จะต้องปรับปรุงคือตัวเนื้อหา ฉันหมายถึงการระบุส่วนสำคัญของโค้ดที่ไม่ได้จัดทำเป็นเอกสาร ส่วนที่ยังไม่ได้จัดทำเอกสารไว้อย่างเพียงพอ หรือโค้ดส่วนที่ล้าสมัยซึ่งควรนำออกจากเอกสารประกอบ เนื่องจากฉันไม่เคยทำงานในโครงการนี้มาก่อน เราจึงต้องได้รับคำแนะนำจากที่ปรึกษาเพื่อให้บรรลุเป้าหมายนี้
แน่นอนว่าเราจะนำทุกอย่างที่ได้จากฝ่ายประชาสัมพันธ์ไปใช้หรือไม่นั้น ขึ้นอยู่กับการปรึกษาหารือกับองค์กร ผมคิดว่าการกระทำนั้นชัดเจนกว่าคำพูด ผมจึงตัดสินใจที่จะแสดงสิ่งที่ทำได้แทนการอธิบายในแอปพลิเคชัน
องค์กรได้ระบุลำดับเวลาคร่าวๆ สำหรับโครงการนี้: งานหลักของสัปดาห์ที่ 0 (ก่อน 9/14) การสนทนาและการตรวจสอบข้อเสนอของสัปดาห์ที่ 1 (9/14) สร้าง Doxygen สัปดาห์ที่ 2 (9/21) การปรับเปลี่ยนสกิน Doxygen (ลำดับความสำคัญต่ำ) สัปดาห์ที่ 0 (ก่อนวันที่ 9/14) การสนทนาและการตรวจสอบข้อเสนอ สัปดาห์ที่ 1 (9/14) สร้าง Doxygen สร้าง สัปดาห์ที่ 2 (9/21) การปรับเปลี่ยนสกิน Doxygen (ลำดับความสำคัญต่ำ) สัปดาห์ที่ 3 (ก่อนสัปดาห์ 9/14) โค้ดทั่วไป - OSystem, FS, เครื่องมือทั่วไป
การเปลี่ยนแปลงเดียวที่ฉันจะเสนอก็คือเริ่มจากการทำงานโครงสร้าง ดังที่ได้กล่าวไปแล้ว ซึ่งสามารถทำได้ในสัปดาห์ที่ 1 และ 2 ควบคู่กับการสร้าง Doxygen (ซึ่งส่วนใหญ่ทำไปแล้ว) และการฟื้นฟูผิวหนังของ Doxygen หลังจากนั้น ดิฉันเห็นว่าการพูดคุยกันในด้านต่างๆ ทีละส่วนร่วมกับที่ปรึกษาเพื่อระบุปัญหาและปรับปรุงเอกสารประกอบเกี่ยวกับดอกซิเจนจึงเหมาะสมที่สุด
ฉันเห็นโปรเจ็กต์ที่มีความยาวมาตรฐาน แต่แน่ใจว่ามีการปรับปรุงอื่นๆ ที่เกี่ยวข้องกับเอกสาร API ซึ่งสามารถทำได้หลังจากโปรเจ็กต์ GSoD เสร็จสิ้น ตัวอย่างเช่น การหาคู่มือสไตล์เอกสารประกอบและเพิ่มลงใน wiki เพื่อให้ผู้มีส่วนร่วมทราบว่าควรจะบันทึกรหัสที่ตนจะเพิ่มไว้อย่างไร
เรายินดีให้ความช่วยเหลือเกี่ยวกับงานเช่นนี้หลังจาก GSoD สิ้นสุด ฉันมั่นใจว่า ScummVM สามารถใช้ผู้เขียนด้านเทคนิคที่จะช่วยให้เอกสาร API ของ API มีคุณภาพและความสามารถในการใช้งานที่ดี เรายังเห็นว่ามีโปรเจ็กต์เอกสารอื่นๆ ในอนาคตที่เราช่วยคุณได้ เช่น การจัดทำคู่มือเกี่ยวกับวิธีทำงานกับปลั๊กอิน