Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- NumPy
- {i>Technical writer <i}(Penulis teknis):
- cooperrc
- Nama project:
- Dokumentasi NumPy untuk Pendidikan Komunitas
- Durasi project:
- Durasi standar (3 bulan)
Project description
Pengantar
NumPy memberikan komputasi berbasis array yang bersih dan cepat dalam library software open source gratis. Ini adalah paket dasar dalam stack SciPy untuk komputasi ilmiah [1]. Lebih dari 370 ribu project menggunakan untuk komputasi array yang efisien [2]. Pengguna NumPy disambut oleh situs baru dengan aplikasi dan studi kasus [1]. Saat pengguna baru menemukan halaman dokumentasi, mereka akan mendapatkan beberapa link “Mulai Di Sini” dan tutorial pengantar yang bisa membingungkan bagi pemula, seperti Dasar-Dasar NumPy/{i>byte-swapping<i}. Saya mulai menggunakan NumPy sepuluh tahun yang lalu di sekolah pascasarjana. Saya harus menggabungkan postingan blog, catatan kuliah, dan jawaban StackExchange untuk menghindari membaca dokumentasi NumPy. Saat ini ada lebih dari 360 ribu percakapan StackExchange yang membahas NumPy. Saya kira pengguna lain memiliki rute yang serupa untuk meraih kesuksesan di NumPy. Elemen penyusun alat pendidikan adalah komunikasi dan komunitas [4]. Dokumentasi harus membangun komunitas yang mencerminkan sasaran proyek yang diinginkan. Dokumentasi harus konsisten dan jelas bagi pengguna baru. Tutorial harus memberikan langkah-langkah yang mudah diikuti kepada pengguna baru dan membangun kenyamanan dengan library [3]. Dokumentasi akan menyambut pengguna baru ke komunitas NumPy. Struktur, kecepatan, dan penulis dokumentasi harus menciptakan tempat yang mendukung eksplorasi dan komunikasi. Proposal ini akan mengatur dan mengisi kekurangan dalam dokumentasi NumPy saat ini sehingga pengguna baru mendapatkan pengetahuan dan disambut dengan baik di komunitas.
Pengetahuan yang disampaikan pengguna diperoleh melalui pengujian dan eksperimen [4,5]. Pengetahuan bergantung pada metode pengujian dan evaluasi. Konten yang memberikan tujuan dan penerapan yang jelas dalam petunjuk memungkinkan pengguna menguji dan mengevaluasi ide dan metode baru. Komunitas dapat membangun basis pengetahuan untuk meningkatkan keterampilan, fakta, dan aplikasi. Ruang cara memberikan manfaat ganda. Pertama, pengguna baru dan berpengalaman memiliki serangkaian sasaran yang jelas untuk menguji dan membuat eksperimen. Kedua, calon kontributor dokumentasi memiliki ruang untuk menyampaikan sasaran, metode, dan solusi mereka. Ruang petunjuk mengisi kebutuhan mendesak untuk membuat dokumentasi NumPy lebih mudah diakses oleh pengguna baru dan kontributor potensial. Pengetahuan Saat Ini
John Dewey mengatakan bahwa fondasi pembelajaran adalah pengalaman yang sebenarnya [4]. Komunitas NumPy memiliki banyak pengalaman asli yang dapat dibagikan kepada pengguna lain. Pendidikan dibangun berdasarkan komunitas dan komunikasi. Halaman dokumentasi yang terorganisir memudahkan pengguna baru untuk menggunakan NumPy. Ini juga membuat template terstruktur bagi calon kontributor untuk menyampaikan pengalaman di NumPy.
Ada empat ruang yang dikelompokkan secara luas untuk dokumentasi software [3]: ruang tutorial, ruang cara, ruang penjelasan, dan ruang referensi. Dokumentasi NumPy memiliki sejumlah dokumen di ruang tutorial yang menggabungkan konten penjelasan dan cara menggunakan ke dalam tutorial. Ruang tutorial harus berfokus pada edukasi pengguna dan menggunakan langkah-langkah yang mudah diulang untuk menyampaikan ide. {i>How-to space<i} menyediakan prosedur yang lebih berorientasi pada tujuan yang dapat diterapkan pengguna di aplikasi dunia nyata. Ruang penjelasan menyediakan informasi terperinci {i>doc-string<i} yang terperinci di setiap fungsi. Ruang tutorial dan petunjuk saat ini tidak digambarkan dengan jelas dan terkadang masuk ke ruang penjelasan dan referensi. Ada tutorial yang sangat bagus untuk “Pemula Mutlak” dan ada referensi yang bagus bagi pengguna Matlab untuk membuat kode NumPy di “Numpy untuk pengguna Matlab”. Menjelaskan keempat ruang ini dengan jelas akan membuat dokumentasi lebih jelas.
Kesenjangan dalam Pusat Informasi/Kebutuhan yang Belum Terpenuhi
Dokumentasi saat ini mencakup banyak topik yang diperlukan, tetapi tidak memiliki perbedaan yang jelas antara ruang tutorial, petunjuk, penjelasan, dan referensi. Hal ini menyebabkan kebingungan bagi calon kontributor. Pengguna baru dapat kewalahan dengan penjelasan dan materi referensi di bagian tutorial, dan calon kontributor menghadapi hambatan untuk berkontribusi. Saya mengusulkan tata letak yang lebih mudah diakses bagi pendatang baru dan kemungkinan kontributor dokumentasi dengan alur yang logis dalam dokumentasi dan mengelola permintaan pull untuk dokumen petunjuk yang dibuat pengguna oleh kontributor baru. Sasaran jangka panjang saya adalah membangun komunitas dokumentasi sehingga belajar dari dokumentasi adalah pengalaman edukasi dan komunikasi yang saling memberi dan menerima. Model dokumentasi ini akan mendasarkan pendidikan pada pengalaman sebenarnya bagi pendatang baru dan calon kontributor.
Alasan
Proposal Google Summer of Docs ini penting untuk tujuan pedagogis dan karier saya. Saya menggunakan NumPy dan SciPy di semua kursus saya. Dokumentasi saat ini sulit diakses oleh siswa saya. Saya ingin menggunakan pengalaman saya dalam mengajar mahasiswa non-CS cara membuat kode untuk membantu mengatur, mengedit, dan mengisi kekurangan dalam tutorial saat ini. Kemudian, saya dapat menggunakan dokumentasi tersebut sebagai buku teks dan materi referensi untuk kursus saya. Saya telah membuat puluhan tutorial, latihan, dan contoh menggunakan Python dan
Sasaran Khusus
Saya memiliki tiga sasaran spesifik untuk proposal Google Summer of Docs ini: 1. Mengatur dokumentasi saat ini, 2. Mengedit tutorial saat ini (Panduan Pemula, Pembuatan Array, Pengindeksan, Aljabar Linear, dan NumPy untuk Matlab) untuk memindahkan informasi referensi ke Ruang Penjelasan, dan 3. Buat materi petunjuk bersama siswa. Setiap sasaran spesifik memiliki hasil yang diharapkan untuk proposal.
Ketiga tujuan spesifik ini dimaksudkan untuk membuat dokumentasi lebih mudah diterima pengguna baru dan memberikan struktur bagi kontributor potensial. Tujuan ini juga membantu mewujudkan tujuan jangka panjang untuk terus mengembangkan komunitas dokumentasi NumPy. Hasil yang Diharapkan
Saya memiliki tiga hasil yang diharapkan sebagai berikut: 1. Halaman dokumentasi revisi yang dengan jelas memisahkan keempat ruang: tutorial, petunjuk, penjelasan, dan referensi, 2. tutorial baru untuk: membaca dan menulis array, pembuatan array (np.zeros, np.ones, np.block, dll.), dan operasi aljabar berbasis elemen vs. linear di NumPy, dan 3. operasi aljabar linier yang dikurasi.
Hasil yang diharapkan ini akan membantu pengguna baru memahami dokumen, memberikan gaya dan format yang jelas kepada calon kontributor dokumentasi, membuat tutorial saat ini lebih singkat dan lebih mudah diikuti, memindahkan penjelasan ke bagian terpisah, dan kontributor dokumentasi baru akan dapat berkontribusi pada kasus penggunaan kecil ke bagian cara melakukannya tanpa membuat seluruh dokumentasi Sphinx. Kami ingin terus membangun komunitas pengajaran dan pembelajaran.
Kontributor dokumentasi baru dapat berkontribusi pada kasus penggunaan kecil kepada jutaan pengguna tanpa mem-build seluruh dokumentasi Sphinx. Kami ingin terus membangun komunitas pengajaran dan pembelajaran. Dokumentasi yang diusulkan ini akan meniru dokumentasi open source saat ini seperti Matplotlib, Divio, dll. Pengguna baru dan calon kontributor akan lebih mudah mempelajari cara menerapkan NumPy di bidang dan software mereka.
Linimasa untuk project ini adalah 14/9-30/11. Langkah pertama adalah membangun dokumentasi dan memisahkan konten dalam tutorial saat ini ke dalam konten Tutorial, Petunjuk, dan Penjelasan. Hal ini akan dilakukan dalam lima minggu pertama project sebagai bagian dari Hasil 1 dan 2, yaitu merevisi situs dan tutorial. Organisasi Dokumentasi yang diusulkan ditampilkan dalam Dokumentasi yang Diusulkan di bawah.
Dokumentasi yang Disarankan:
i.Tutorials:
- Dasar-dasar mutlak untuk pemula (hapus penginstalan, dapatkah impor/ekspor pandas diganti dengan numpy.loadtxt?)
- link ke “Apa itu numpy”
- link ke petunjuk penginstalan dasar di sini
- Tutorial Mulai Cepat (dimaksudkan untuk tindak lanjut tutorial Python)
- Menggunakan array NumPy
- pembuatan array (np.zeros, np.ones, np.block, dll.) (tulis: prioritas sedang-rendah)
- operasi element-wise (+,-,*,/) dan operasi aljabar linear (+,-,@, linalg.solve) (prioritas tulis:med)
- Membaca dan menulis data menggunakan Numpy (tulis: prioritas tinggi)
- Pengindeksan
ii. Petunjuk:
- Linear Algebra on n-dimensional arrays (would love to edit the headings and descriptions and maybe change title to “Image processing with Numpy’s linear algebra”)
- link ke konten petunjuk tutorial numpy (pekerjaan yang sedang berlangsung)
iii. Penjelasan:
- Jenis data
- I/O dengan Numpy
- Pengindeksan
- Penyiaran
- Pertukaran byte
- Array terstruktur
- Menulis penampung array kustom
- subclassing ndarray
- Lain-lain
iv. Ruang Referensi:
- Glosarium
- Referensi Numpy API
- Numpy untuk pengguna Matlab (tabel ekuivalensi adalah tabel referensi yang bagus, tetapi diskusi array/matriks mengganggu dan tampaknya tidak digunakan lagi)
Setelah menyelesaikan Google Dokumen Musim Google ini, saya mengusulkan hasil berikut:
- Halaman Web Dokumentasi yang direvisi yang memisahkan empat ruang dengan jelas: Tutorial, Cara, Penjelasan, dan Referensi
- Tutorial Baru untuk: pembuatan array (np.zeros, np.ones, np.block, dll.), operasi elemen per elemen (+,-,*,/) dan operasi aljabar linear (+,-,@, linalg.solve), serta Membaca dan menulis data menggunakan Numpy (prioritas tinggi)
- Menyarankan dokumen petunjuk untuk meningkatkan kontribusi pengguna dan membantu mewujudkan tujuan komunitas dalam pengajaran dan pembelajaran
Setiap hasil memiliki sejumlah langkah yang diuraikan di bawah dalam tabel untuk Hasil 1-3. Saat Dokumentasi yang Diusulkan dikirim untuk ditinjau, tutorial “Array baca/tulis” prioritas tinggi akan ditulis untuk dikirim sebagai permintaan pull sebagai bagian dari Hasil 2. Selama peninjauan situs yang direvisi dan tutorial “Membaca/Menulis array” yang diperbarui, saya akan mulai menulis tutorial untuk membuat array menggunakan fungsi NumPy, misalnya np.ones, np.zeros, np.diag. Sisa waktu akan digunakan untuk merespons masalah permintaan pull dan mulai menulis tutorial peringkat 3: Operasi aljabar linear dan berbasis elemen di Python.
Hasil ketiga adalah menasihati siswa di University of Connecticut untuk membuat dokumentasi di repositori tutorial numpy. Tutorial atau dokumen petunjuk yang dikirimkan akan berupa notebook Jupyter yang menggunakan NumPy untuk memecahkan masalah teknik. Saya akan menggunakan beberapa catatan/contoh materi untuk mengirimkan contoh notebook. Saya akan menyarankan siswa untuk mengikuti tata letak dan struktur saat kita membuat template dan skema framing. Hasil ini memberikan pengalaman yang nyata bagi siswa untuk menyampaikan konsep dan solusi kepada audiens yang lebih luas. Ini adalah kesempatan besar bagi siswa untuk bergabung dengan komunitas NumPy dan belajar.
Hasil 1: Merevisi situs Tanggal Hasil Membuat Fork Repositori dan Membuat Dokumen dengan Sphinx 21/9 Membuat Halaman Web dengan Empat Ruang yang ditentukan dan ditautkan 1/10 Memindahkan tutorial saat ini ke ruang yang sesuai dan Membuat dokumen 10/10 Mengirimkan PR ke github dengan perubahan yang diusulkan 11/1 Merespons komentar/saran dan merevisi PR sedang berlangsung dengan Hasil 2 Situs direvisi 30/11
Hasil 2: Merevisi tutorial Tanggal Pelaksanaan Meninjau tutorial peringkat revisi 9/21 Memisahkan konten tutorial saat ini ke dalam ruang Tutorial dan Penjelasan 10/1 Menulis peringkat 1: Membaca/Menulis array 10/10 Mengirim PR ke github untuk pemisahan dan revisi 10/20 Menulis peringkat 2: Operasi Pembuatan Array/11/15 Menulis peringkat Array/Membuat PR3/15 Menulis urutan pembuatan Array
Usulan peringkat revisi tutorial (dapat berubah sesuai dengan mentor/komunitas):
Array Baca/Tulis saat ini halaman kosong
Pembuatan array (np.zeros, np.ones, np.block, dll.) Tidak ada: akan membantu pengguna baru untuk mendapatkan penjelasan dan demonstrasi alat pembuatan/interaksi array umum
Operasi elemen dan aljabar linear (+,-,*,/ dan +,-@,linalg.solve) Tidak ada: ini sangat membantu untuk 1. Pengguna Matlab dan 2. Orang yang mengadopsi aljabar linear (machine learning, regresi linear, dll.)
Hasil 3: Ruang Cara yang diseleksi Tanggal Hasil Link Eksternal(masalah/contoh)
Membuat contoh Cara (kandidat: Cara menemukan frekuensi alami senar gitar 20/10
Membuat template Cara untuk kontributor baru 1/10 dalam proses PR template Tutorial & Menyusun kemungkinan kontribusi
Bekerja sama dengan kontributor lain untuk membuat notebook Cara merekrut siswa UConn dan anggota komunitas lainnya Status 1/7: kerja-studi disetujui dan aplikasi diterima
Signifikansi yang Diharapkan
Proposal Google Summer of Docs ini akan membuat dokumentasi NumPy , mengisi tutorial yang terlewat dari situs web, dan mendapatkan kontributor dokumentasi. Sebagai Profesor di bidang Teknik Mesin, saya berencana untuk menyegmentasikan dokumentasi sedemikian rupa sehingga siswa saya dapat menjelajahi dokumen dan dengan mudah menemukan tutorial pengantar vs panduan cara melakukan praktik langsung. Dokumentasi yang tersegmentasi: tutorial, cara, referensi, dan penjelasan akan memberi calon kontributor contoh terstruktur untuk membuat resource baru. Dokumentasi yang diusulkan cocok untuk saling memberi dan menerima melalui pengalaman edukasi dan komunikasi bagi pengguna baru dan berpengalaman. Dokumen cara yang diusulkan untuk memberikan saran kepada siswa University of Connecticut akan menerapkan ide edukasi dan komunikasi ini. Kami ingin semua pengguna menemukan ruang untuk bereksperimen, belajar, dan bergabung dengan komunitas NumPy.
Referensi
- Situs NumPy.org diakses pada 07/2020.
- Repositori GitHub NumPy.
- Sistem Dokumentasi. Divio.com diakses 07/2020.
- Dewey, Joni. Demokrasi dan Pendidikan. Project Gutenberg, Agustus 2015.
- Dewey, John. Quest for Certainty George Allen And Unwin Limited. 06/2005.