Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan proyek
- Organisasi open source:
- SciPy
- Penulis teknis:
- mkg33
- Nama project:
- Dokumentasi yang berorientasi pada pengguna dan penyusunan ulang yang menyeluruh
- Durasi project:
- Durasi standar (3 bulan)
Project description
Motivasi:
Saya ingin mengerjakan pemfaktoran ulang dokumentasi yang ada, sehingga mudah diakses oleh pengguna dengan berbagai kebutuhan. Tidak perlu dikatakan bahwa peneliti kemungkinan besar tertarik dengan fitur lanjutan dan halus, sedangkan pengguna tanpa keahlian sebelumnya akan menghargai panduan dan diagram langkah demi langkah.
Saya tertarik untuk melanjutkan project ini karena alasan pribadi dan profesional: pertama-tama, saya ingin berkontribusi secara signifikan pada SciPy karena riset saya sendiri telah sangat diuntungkan darinya dan kedua, saya sering kali menemukan dokumentasi yang tidak memadai (atau kurang) di software lain dan selalu bertanya-tanya seberapa cepat (jika sama sekali!) pengguna dapat mempelajari cara menggunakan kode jika mereka telah diberi panduan yang menyeluruh.
Sasaran:
Saya ingin meningkatkan dokumentasi SciPy yang ada, baik dari segi konten maupun grafis. Fitur terpenting dari pendekatan saya terhadap masalah ini adalah deployment dan analisis survei pengguna, yaitu survei ringkas yang dilakukan secara online yang memungkinkan berbagai pengguna menyampaikan kebutuhan mereka terkait dokumentasi. Saya sangat percaya bahwa pendapat mereka harus menjadi sumber inspirasi (bagaimana lagi kita bisa membuat dokumentasi yang lebih mudah digunakan?).
Sehubungan dengan realisasi project itu sendiri, fase pertama akan melibatkan desain dan analisis survei pengguna, serta mengatasi beberapa masalah gaya yang saya perhatikan dalam dokumentasi saat ini. Misalnya, kurangnya konsistensi (contoh: array 2 dimensi yang muncul bersama array 2 dimensi), kalimat berbelit-belit yang harus ditulis ulang, atau kurangnya urutan alfabet di subhalaman tertentu. Fase kedua akan berfokus pada pengenalan panduan grafis yang berisi hyperlink ke topik yang relevan (berdasarkan hasil survei dan permintaan komunitas lainnya). Dalam jangka panjang, saya ingin mencapai dokumentasi yang memuaskan dan disesuaikan dengan berbagai jenis pengguna. Selain itu, saya akan mencoba membuat tutorial lebih konsisten baik secara linguistik maupun struktural. Terakhir, saya ingin menulis tutorial baru (berdasarkan kebutuhan komunitas saat ini).
Survei pengguna:
Sehubungan dengan survei pengguna, saya mengusulkan untuk menggunakan Google Formulir karena beberapa alasan. Pertama-tama, Google Formulir gratis dan menawarkan fungsionalitas tanpa batas (dalam hal jumlah responden, pertanyaan, dll.), memiliki bentuk visual yang menarik, opsi survei yang paling berguna (misalnya, skala linear yang dapat disesuaikan, kotak centang, dan pilihan ganda), dan yang terpenting, hasilnya dapat dengan mudah diekspor untuk keperluan analisis statistik. Berdasarkan riset online, tampaknya Google Formulir, setidaknya untuk saat ini, adalah alat gratis terbaik untuk melakukan survei. Dalam catatan yang tidak terlalu serius, akan lebih baik jika Anda menggunakan produk Google dalam inisiatif yang dijalankan Google.
Saya telah membuat survei awal dengan contoh pertanyaan (dapat diakses di https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Jumlah pertanyaan yang wajar dalam versi akhir harus antara sepuluh dan lima belas. Untuk mendapatkan hasil yang konkret, sebaiknya kita biasanya menggunakan pertanyaan pilihan ganda, skala linier, dan beberapa kotak centang. Skala linier tidak boleh menyerupai spektrum penuh (hal itu hanya menyebabkan kebingungan dan hasilnya cenderung mengalami dispersi yang tinggi). Sebaiknya ada maksimal dua pertanyaan terbuka. Jika tidak, hasilnya akan sangat tersebar dan tidak membantu sama sekali. Saya rasa bahkan jumlah respons yang sangat tinggi tidak akan menjadi masalah karena data dapat diekspor dengan mudah dan dianalisis secara otomatis dengan software statistik. Dengan asumsi bahwa jumlah respons memang sangat tinggi, analisis pertanyaan terbuka mungkin sedikit memakan waktu, tetapi saya yakin hal itu tidak akan terlalu membebani. Lagi pula, rata-rata pengguna tidak mungkin menulis esai tentang keadaan dokumentasi. Dalam skenario terburuk, beberapa jawaban dapat disimpan untuk analisis mendatang.
Panduan grafis:
Visi saya tentang panduan grafis (yang dimaksudkan untuk berfungsi sebagai alat navigasi) didasarkan pada premis populer bahwa (sebagian besar) manusia lebih baik dalam memproses struktur visual yang sederhana, bukan informasi berbasis teks semata. Selain itu, diagram yang berorientasi tematik dengan garis yang menghubungkan topik minat yang serupa, tidak diragukan lagi, merupakan aset yang sangat berharga bagi pengguna yang kurang berpengalaman (dan bukan hanya itu).
Sehubungan dengan detail penerapan, saya mengusulkan untuk menggunakan paket TikZ. Pertama-tama, ini adalah alat yang canggih dan tampaknya tidak berisiko akan segera dihentikan. TeX juga menawarkan output berkualitas tinggi, memiliki dokumentasi yang sangat solid, dan merupakan topik yang sering dibahas di TeX StackExchange dan forum mainstream lainnya. Yang paling penting, integrasi file TikZ (lebih tepatnya, banyak hyperlink di dalamnya) dengan dokumentasi HTML tampaknya tidak menimbulkan masalah yang signifikan karena adanya berbagai paket dan perbaikan untuk menyematkan gambar TikZ di HTML (misalnya, TeX4ht).
Pertanyaan tentang pemeliharaan panduan di SciPy pada masa mendatang dapat dengan mudah dipecahkan dengan menggunakan, misalnya, Overleaf (memfasilitasi kolaborasi serta menawarkan pratinjau instan) dan template standar yang akan saya sediakan. Pada dasarnya, panduan grafis cenderung tidak terlalu berbeda satu sama lain. Struktur, palet warna, dan bentuknya, kurang lebih, akan berbeda, oleh karena itu pembentukan ulang berikutnya dan penyesuaian lebih lanjut tidak akan menjadi masalah.
(Lihat versi lengkap proposal - tersedia di folder GSoD bersama.)