Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.
Ringkasan proyek
- Organisasi open source:
- SciPy
- Penulis teknis:
- mkg33
- Nama proyek:
- Dokumentasi yang berorientasi pada pengguna dan restrukturisasi menyeluruh
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
Motivasi:
Saya bermaksud mengerjakan pemfaktoran ulang dokumentasi yang ada, sehingga akan mudah diakses oleh pengguna dengan kebutuhan yang berbeda. Tidak perlu dikatakan bahwa peneliti kemungkinan besar tertarik pada fitur lanjutan dan halus, sedangkan pengguna tanpa keahlian sebelumnya menghargai panduan dan diagram langkah demi langkah.
Saya tertarik mengikuti project ini karena alasan pribadi dan profesional: pertama-tama, saya ingin berkontribusi secara signifikan ke SciPy karena riset saya sendiri sangat diuntungkan darinya dan kedua, saya terlalu sering mendapati dokumentasi yang tidak memadai (atau kurang) dalam software lain dan selalu bertanya-tanya seberapa cepat (jika semuanya!) pengguna dapat mempelajari cara menggunakan kode jika mereka diberi panduan menyeluruh.
Sasaran:
Saya ingin meningkatkan kualitas dokumentasi SciPy yang ada baik dari segi konten maupun grafis. Fitur terpenting dari pendekatan saya terhadap masalah ini adalah penerapan dan analisis survei pengguna, yaitu survei singkat yang dilakukan secara {i>online<i} yang memungkinkan berbagai pengguna untuk menyuarakan kebutuhan mereka mengenai dokumentasi. Saya sangat percaya bahwa pendapat mereka harus menjadi sumber inspirasi (bagaimana lagi kita bisa membuat dokumentasi yang lebih ramah pengguna?).
Mengenai realisasi proyek itu sendiri, fase pertama akan melibatkan perancangan dan analisis survei pengguna, serta menangani beberapa masalah gaya yang telah saya perhatikan dalam dokumentasi saat ini. Misalnya, kurangnya konsistensi (contoh: array 2 dimensi yang terjadi bersamaan dengan array dua dimensi), kalimat berbelit-belit yang harus ditulis ulang, atau kurangnya urutan abjad di subhalaman tertentu. Fase kedua akan berfokus pada pengenalan panduan grafis yang berisi tautan ke topik yang relevan (berdasarkan hasil survei dan permintaan komunitas lainnya). Dalam jangka panjang, saya ingin mendapatkan dokumentasi yang memuaskan dan disesuaikan untuk berbagai jenis pengguna. Selain itu, saya akan mencoba untuk merender tutorial secara lebih konsisten baik secara linguistik maupun struktural. Terakhir, saya ingin menulis tutorial baru (berdasarkan kebutuhan komunitas saat ini).
Survei pengguna:
Terkait 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 linier yang dapat disesuaikan, kotak centang, dan pilihan ganda), dan yang terpenting, hasilnya dapat dengan mudah diekspor untuk keperluan analisis statistik. Berdasarkan riset online, tampaknya untuk saat ini Google Formulir adalah alat gratis terbaik untuk melakukan survei. Pada dasarnya, akan lebih baik jika 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 masuk akal pada versi akhir harus antara sepuluh hingga lima belas. Untuk mendapatkan hasil yang konkret, kami menyarankan agar kita terutama menggunakan pertanyaan pilihan ganda, skala linier, dan beberapa kotak centang. Skala linear seharusnya tidak menyerupai spektrum penuh (hanya menyebabkan kebingungan dan hasilnya cenderung mengalami dispersi yang tinggi). Seharusnya ada maksimal dua pertanyaan terbuka, jika tidak, hasilnya akan sangat tersebar dan tidak membantu sama sekali. Menurut saya, jumlah respons yang sangat banyak pun tidak akan menjadi masalah karena data tersebut dapat dengan mudah diekspor dan dianalisis secara otomatis menggunakan software statistik. Dengan asumsi bahwa jumlah respons memang sangat tinggi, analisis pertanyaan terbuka bisa sedikit memakan waktu tetapi saya rasa itu tidak akan berlebihan. Lagi pula, rata-rata pengguna tidak mungkin menulis esai tentang status dokumentasi. Dalam skenario kasus terburuk, beberapa jawaban dapat disimpan untuk analisis di masa mendatang.
Panduan grafis:
Visi saya tentang panduan grafis (dimaksudkan untuk berfungsi sebagai alat navigasi) didasarkan pada premis populer bahwa (sebagian besar) manusia lebih baik dalam memproses struktur visual yang sederhana daripada informasi berbasis teks saja. Selain itu, diagram berorientasi tema dengan garis-garis yang menghubungkan topik-topik menarik yang serupa, tidak diragukan lagi, adalah aset yang sangat berharga untuk pengguna yang kurang berpengalaman (dan bukan hanya).
Terkait detail implementasi, saya mengusulkan untuk menggunakan paket TikZ. Pertama dan terpenting, YouTube adalah alat yang andal dan tampaknya tidak berisiko untuk dihentikan dalam waktu dekat. Ia juga menawarkan output berkualitas tinggi, memiliki dokumentasi yang sangat solid, dan merupakan topik yang sering dibahas di TeX StackExchange dan forum umum 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 dalam HTML (misalnya, TeX4ht).
Pertanyaan tentang pengelolaan panduan di masa mendatang dalam SciPy bisa dengan mudah diselesaikan menggunakan, misalnya, Overleaf (memfasilitasi kolaborasi serta menawarkan pratinjau instan) dan template standar yang akan saya sediakan. Pada dasarnya, panduan grafis tidak terlalu berbeda satu sama lain. Struktur, palet warna, dan bentuk, kurang lebih, akan menjadi invarian, karena itu pembentukan ulang dan penyesuaian lebih lanjut selanjutnya tidak akan menjadi masalah.
(Harap lihat versi lengkap proposal - tersedia di folder GSoD bersama.)