Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan proyek
- Organisasi open source:
- Bahasa Julia
- Penulis teknis:
- mkg33
- Nama proyek:
- Dokumentasi terpadu Scientific Machine Learning
- Durasi project:
- Berjalan lama (5 bulan)
Project description
Saya ingin mengerjakan penyatuan organisasi SciML karena ada banyak ruang untuk peningkatan di area ini dan penyelesaian project ini tidak diragukan lagi akan memberikan manfaat langsung bagi programmer Julia dan kontributor/pemelihara aktif SciML. Paket yang tersebar di seluruh SciML menawarkan beberapa alat yang sangat berguna, tetapi selalu ada bahaya bahwa paket tersebut mungkin tidak akan diketahui (terutama oleh pendatang baru) hanya karena pengguna tidak dapat menemukan paket dan menerapkannya ke masalah yang dihadapi.
Ini agak membuat frustrasi mengingat tujuan utama dari paket ini adalah untuk menjangkau khalayak yang luas, baik {i>programmer<i} (pemula maupun ahli). Untuk menghindari situasi yang dijelaskan di atas, saya mengusulkan untuk merevisi 'halaman depan' dokumentasi SciML secara menyeluruh dan membuat semacam hub yang dapat digunakan pengguna untuk menjelajahi paket terkait dan mempelajari ekosistem yang berkembang. Hal ini juga dapat berfungsi sebagai titik referensi yang berharga bagi pengguna yang lebih berpengalaman dan memungkinkan mereka bekerja lebih efisien.
Pertama-tama, dokumentasi yang ada untuk semua paket individu perlu revisi sehubungan dengan masalah gaya yang paling dasar (seperti ejaan, tanda baca, tata bahasa, dll.). Untuk memastikan konsistensi gaya, SciML perlu memiliki panduan gaya konkret (sangat diperlukan untuk membuat perubahan retrospektif dan untuk referensi di masa mendatang). Akan sia-sia jika Anda memulai dari awal. Sebaliknya, video tersebut harus didasarkan pada konvensi Julia yang ada dan menyertakan keseluruhan konten baru untuk masalah khusus SciML.
Setelah panduan gaya selesai, saya ingin merevisi dokumentasi saat ini di fase kedua project. Ini akan membuat dokumentasi terlihat lebih profesional dan stabil. Saya telah membuat beberapa permintaan pull yang menggambarkan pendekatan saya terhadap tugas ini. Pada fase ini, saya juga bermaksud untuk merancang (dan menerapkan) sistem kutipan yang efisien. Tugas pertama adalah memperbarui halaman kutipan yang sudah tidak berlaku.
Fase ketiga, yang bisa dibilang paling penting, akan melibatkan desain roadmap SciML, yang akan menekankan interaksi antara paket yang tersebar. Makin kuat kohesi antara dua paket (sehubungan dengan masalah atau kode itu sendiri), makin dekat keduanya akan muncul dalam daftar 'lihat juga'. Saya mengusulkan untuk membuat dua kunci rekomendasi: satu untuk kemiripan kode dan satu untuk kesamaan masalah. Dengan demikian, pengguna akan dapat mengidentifikasi paket lain yang berpotensi berguna dengan lebih cepat daripada dengan menjelajahi repositori dan dokumentasi masing-masing dengan susah payah. Alih-alih mencantumkan semua koneksi yang mungkin di antara paket, saya lebih suka fokus pada yang lebih besar dan mencoba menyajikan tautan mereka dengan paket yang lebih kecil (metode ini juga akan diperluas untuk memperbarui tutorial di mana koneksi dengan paket lain harus ditunjukkan). Pendekatan ini menjamin bahwa daftar 'lihat juga' akan informatif tanpa menjadi enumerasi lengkap kombinasi paket.