Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- ScummVM
- {i>Technical writer <i}(Penulis teknis):
- b-gent
- Nama project:
- Meningkatkan dokumentasi kode sumber melalui Doxygen
- Durasi project:
- Durasi standar (3 bulan)
Project description
Dokumentasi ScummVM API (kode sumber) saat ini dipublikasikan di sini: https://doxygen.scummvm.org/modules.html
Sayangnya, fitur ini masih kurang dalam banyak hal:
1) Praktis tidak ada struktur padanya, semua informasi mengambang pada tingkat yang sama.
2) Elemen C++ didokumentasikan secara tidak konsisten dengan beberapa di antaranya tidak didokumentasikan sama sekali. Hal ini disebutkan oleh organisasi sebagai salah satu masalah utama.
3) Konten usang dan tidak digunakan lagi masih ditampilkan di output.
4) Bahasa dan penggunaan pemberian tag doksigen harus dibuat lebih konsisten. Diperlukan serangkaian aturan untuk hal ini, sesuatu yang dapat menjadi dasar untuk panduan gaya dokumentasi di masa mendatang untuk project ini.
5) CSS doxygen yang digunakan di halaman ini dapat ditingkatkan agar lebih mirip dengan situs ScummVM: https://www.scummvm.org
Semua masalah ini dapat diatasi selama project Season of Docs.
Permohonan Season of Docs ini disertai dengan draf PR yang saya buka dalam project untuk menunjukkan beberapa potensi peningkatan yang saya usulkan: https://github.com/scummvm/scummvm/pull/2361 Lihat deskripsi di sana untuk mengetahui beberapa detail tentang isinya dan melihat perbedaannya.
Berikut adalah hal-hal yang terkait dengan PR:
1) Saya rasa hal yang paling membingungkan saat ini bagi calon kontributor baru, dan umumnya semua orang yang melihat dokumen API saat ini, adalah kurangnya struktur. Memperkenalkan dokumentasi API terstruktur akan meningkatkan keterbacaan, kemudahan ditemukan, dan, akibatnya, kegunaan set dokumen. Itu sebabnya PR saya memperkenalkan grup doxygen ke semua file {i>header<i} di folder 'common'. Dengan struktur baru ini, jika seseorang ingin menemukan dokumen untuk API terkait OS (misalnya), mereka dapat dengan mudah menemukannya di navigasi.
2) File konfigurasi doxygen baru disiapkan untuk memungkinkan pembuatan dokumentasi ini.
3) File 'links.doxyfile' yang dapat digunakan sebagai sumber tunggal untuk semua link yang digunakan di seluruh set dokumen. Mekanisme yang berguna saat menggunakan doxygen.
4) CSS doxygen yang dimodifikasi. Saat ini, ini diambil dari project open source lain dan hanya merupakan titik awal. Idealnya, tampilan dan nuansa halaman doxygen harus kurang lebih konsisten dengan halaman web ScummVM.
Hal yang tidak dicakup oleh PR, tetapi harus dikerjakan, adalah konten itu sendiri. Maksud saya adalah mengidentifikasi bagian penting dari kode yang tidak didokumentasikan, bagian yang tidak cukup didokumentasikan, atau bagian kode usang yang harus dihapus dari dokumentasi. Karena saya belum pernah bekerja dalam project ini sebelumnya, saya memerlukan bimbingan dari mentor untuk mencapainya.
Tentu saja, apakah kita akan menerapkan apa pun dari PR tersebut bergantung pada diskusi dengan organisasi. Ide saya adalah tindakan lebih bermakna daripada kata-kata, jadi saya memutuskan untuk menunjukkan apa yang dapat saya lakukan, bukan hanya mendeskripsikannya dalam aplikasi.
Organisasi telah memberikan perkiraan linimasa berikut untuk project ini: Minggu Tugas utama Minggu 0 (Sebelum 14/9) Diskusi & peninjauan proposal Minggu 1 (14/9) Penyiapan build Doxygen Minggu 2 (21/9) Pembaruan skin Doxygen (prioritas rendah) Minggu 3 (28/9) Kode umum - OSystem, FS, Struktur Data, String, dll. Minggu 4 (05/10) Kode umum - Lanjutan Minggu 5 (12/10) Mesin - Kode umum & contoh mesin Minggu 6 (19/10) Grafik Minggu 7 (26/10) Audio Minggu 8 (02/11) Video, Gambar Minggu 9 (09/11) Backend - Platform, Grafik, Peristiwa Minggu 10 (23/11) Backend - Lanjutan Minggu 11 (30/11) Ringkasan dan pengiriman project
Satu-satunya perubahan yang akan saya sarankan adalah memulai dengan mengerjakan struktur, seperti yang telah disebutkan. Ini dapat dilakukan di minggu 1 &2, bersama dengan pengaturan build doxygen (yang sebagian besar sudah dilakukan) dan penyegaran kulit Doxygen. Setelah itu, saya setuju bahwa akan sangat masuk akal untuk membahas berbagai bidang satu per satu bersama mentor untuk mengidentifikasi masalah dan meningkatkan dokumentasi doksigen.
Saya melihat ini sebagai project berdurasi standar, tetapi saya yakin ada peningkatan lain terkait dokumentasi API yang dapat dilakukan setelah project GSoD selesai. Misalnya, membuat panduan gaya dokumentasi dan menambahkannya ke wiki, sehingga kontributor mengetahui cara mendokumentasikan kode yang mereka tambahkan.
Kami akan dengan senang hati membantu tugas seperti ini setelah GSoD berakhir. Saya yakin ScummVM dapat meminta penulis teknis yang akan memastikan bahwa dokumen API-nya memiliki kualitas dan kegunaan yang baik. Saya juga melihat bahwa ada project dokumen lain di masa mendatang yang dapat saya bantu, seperti membuat panduan tentang cara menggunakan plugin.