Halaman ini berisi detail proyek penulisan teknis yang diterima untuk Google Season of Dokumen.
Ringkasan proyek
- Organisasi open source:
- Matplotlib
- Penulis teknis:
- jeromev
- Nama proyek:
- Mengembangkan Jalur Entri Matplotlib
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
Pengantar
Saran proyek Matplotlib untuk Google Season Dokumen tahun ini melibatkan pembuatan konten yang membantu memperkenalkan Matplotlib kepada pengguna baru. Untuk Mengembangkan Jalur Entri Matplotlib, saya mengusulkan pendekatan alternatif untuk dokumentasi saat ini. Saya seorang penulis teknis baru di industri ini, tetapi saya memiliki latar belakang di bidang yang terkait dengan pendidikan dan pendidikan. Penulisan teknis dan pendidikan memiliki kesamaan kuat yang berfokus pada produksi konten yang berempati dan memungkinkan pengguna menyelesaikan tugas mereka dengan referensi yang disediakan.
Dalam konteks ini, dokumentasi Matplotlib akan mendapat manfaat dengan peningkatan untuk berempati dengan pengguna baru. Sebagian besar materi pada saat ini terdiri dari data acak dan visual tidak berlabel. Class ini sangat bagus untuk menampilkan visual dan fitur Matplotlib dengan cepat. Namun, untuk kasus penggunaan seseorang yang baru mengenal Matplotlib, akan sulit untuk melewati transformasi data ke visual.
Konteks dalam pendekatan ekspositori adalah solusi untuk kendala ini. Dengan menulis prosedur melalui contoh dari dunia nyata, kita menunjukkan pemahaman tentang lingkungan di mana pengguna bekerja. Hal ini memperbaiki hubungan dokumentasi dan pengguna dalam hal mencapai tujuan atau ekspektasi dalam menyelesaikan tugas.
Pengguna memiliki tujuan turunan yang konsisten. Misalnya, data scientist di perusahaan sepatu harus menyajikan data pelanggan kepada tim untuk mengilustrasikan tren belanja dari waktu ke waktu. Dalam situasi ini, pengguna harus belajar menavigasi Matplotlib dan memanfaatkan {i>tool<i} di dalam {i>library<i} untuk menyelesaikan tugas yang ada.
Dengan konteks tambahan untuk mendukung dokumentasi, pengguna baru mungkin lebih dapat memahami topik tersebut. Tujuan turunan pengguna paralel dengan dokumentasi. Saya berharap dapat mewujudkan visi yang dibahas oleh Lead Developer Tom Caswell dalam sebuah wawancara pada tahun 2017 sebagai "memiliki seseorang yang benar-benar dapat menulis dan memiliki empati terhadap pengguna, untuk menelusuri dan pada dasarnya menulis buku 'Intro to Matplotlib' sepanjang 200 halaman, dan menjadikan itu sebagai entri utama ke dokumen."
Pendekatan Alternatif Tulisan Ekspansi
Dokumentasi saat ini menunjukkan fitur Matplotlib, yaitu hal-hal yang dapat dilakukan pengguna dengan {i>library<i}. Misalnya, tutorial sering kali mengikuti pola yang tidak melibatkan penjelasan tentang metode yang mendasarinya.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
Sering kali dengan dukungan dan dokumentasi pemrograman, pengguna disarankan untuk menjalankan kode sendiri untuk memahami apa yang terjadi. Meskipun pola pikir pemrograman meningkatkan pemahaman pengguna tentang topik, kurva belajar untuk transformasi memiliki sedikit konten pendukung. Hal ini dapat menjadi tantangan yang berat karena dokumentasi terbatas.
Menyediakan diagram, gambar, atau visual tambahan lainnya akan membantu menciptakan peluang pembelajaran baru. Struktur di bawah ini juga akan berfungsi dengan baik sebagai template untuk konten baru. Selain itu, menambahkan gambar atau grafik non-tekstual juga dapat memanfaatkan fitur seperti info dan pelatihan. Ada kalanya gambar lebih sulit dijelajahi tanpa indikasi bagaimana atau di mana kode ditransformasi menjadi output yang dieksekusi. Saya percaya bahwa ada elemen visual kuat yang hilang yang dapat mendorong pemahaman yang lebih besar tentang topik.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
Ada potensi besar dalam pendekatan alternatif ini, yaitu penggunaan penulisan ekspositori untuk dokumentasi. Dengan melihat berbagai konsep untuk transformasi, pengguna akan dapat mengidentifikasi strategi dasar pengembangan visualisasi ke data dengan lebih baik. Pengetahuan ini dapat membantu pengguna berinovasi dan memanfaatkan fitur yang ditampilkan oleh contoh berdasarkan kasus penggunaan yang realistis.
Seiring dengan semakin populernya Matplotlib, konsistensi dalam kemudahan penggunaan dan kemudahan pendekatan adalah bukti reputasi perpustakaan. Karakteristik ini dapat menunjukkan pola dan strategi umum yang tidak hanya dapat muncul dalam kode, tetapi juga dalam dokumentasi. Jika Matplotlib mudah dan standar bagi pengguna untuk diprogram, terbukti dalam penggunaannya yang terus berkembang dan sumber daya yang berkembang, itu juga bisa menjadi cara untuk dokumentasi teknis.
Saat pengguna mengalami masalah, biasanya menggunakan penelusuran untuk menyelesaikannya. Daripada mengandalkan penelusuran sebagai metode utama navigasi, akan lebih berdampak jika pengguna membuat kurikulum mereka sendiri dalam dokumentasi. Dalam hal ini, pengguna mencari solusi untuk masalah mereka, lalu ketika mereka menemukan masalah lain atau menginginkan informasi tambahan, mereka akan menggunakan tautan yang disematkan dan menyeluruh.
Hal ini akan melibatkan arsitektur {i>bottom-up <i}dalam sistem organisasi. Untuk setiap topik di Matplotlib, jaringan tautan yang lengkap ke minat subjek serta topik informasi akan membantu membangun jaringan yang efektif. Melalui jaringan ini, pengguna akan lebih cenderung untuk terus menggunakan dokumentasi saat mereka menavigasi ke topik mereka dan menjelajahi lebih banyak informasi yang terkait dengan topik tersebut.
Hambatan
Selalu ada tantangan dalam sebuah proyek yang sekomprehensif dan sedetail ini. Sebagai penulis teknis baru di industri ini, saya memiliki keterbatasan pengalaman menggunakan Sphinx dan ReST untuk menulis dokumentasi. Saya juga seorang pemula dalam hal Matplotlib serta Git. Menangani keempat sistem ini dan membiasakan diri untuk menggunakannya untuk kolaborasi dan riset memerlukan waktu. Saya perlu mendelegasikan waktu selama fase ikatan komunitas dan lebih awal guna membangun fondasi yang diperlukan untuk jalur pemula. Selama periode ini, jika saya mengalami masalah terkait konsep dan dasar, saya perlu menghubungi komunitas untuk mendapatkan dukungan tambahan.
Mengkoordinasikan upaya kolaboratif lintas zona waktu dan melalui platform online juga memerlukan beberapa penyesuaian. Ada berbagai cara komunikasi yang digunakan orang-orang di seluruh industri, jadi kami harus memastikan bahwa saya dapat diakses dan digunakan di semua media. Saya akan bersikap transparan dalam menentukan prioritas saya atas berbagai ekspektasi. Meskipun saya baru memulai dengan melakukan pekerjaan seperti ini di industri ini, saya berinvestasi untuk membuat diri saya bertanggung jawab dan terbuka terhadap masukan dan kritik. Saya merasa kualitas ini berharga di bidang apa pun.
Selain itu, meningkatkan pengujian {i>usability<i} adalah bagian dari dokumentasi yang saya yakini akan menguntungkan jalur entri Matplotlib. Survei untuk kegunaan terkait konten bertujuan untuk memberikan profil pengguna, yaitu persona. Informasi seperti pengalaman pengguna, industri mereka, dan riwayat pemecahan masalah sangatlah berharga. Bagian-bagian ini membantu membentuk bahasa di balik prosedur. Saat menulis dan menjangkau pembaca di tingkat mereka, konten matang, tidak hanya berfungsi sebagai instruksional.
Perjuangan besar sering kali terletak pada terciptanya praktik pengujian kegunaan yang berkelanjutan. Sangat umum untuk memiliki satu instance pengujian, jika dilakukan, selama pengembangan konten. Pengujian kegunaan rutin membantu mendorong narasi konten. Saya berharap dapat mengatur jadwal atau melakukan uji {i>usability<i} berulang dengan komunitas Matplotlib.
Kesimpulan
Saya memiliki sedikit pengalaman menggunakan Python dan Matplotlib di waktu luang saya. Jumlah yang saya pelajari sendiri selama beberapa bulan terakhir adalah dengan dukungan dokumentasi saat ini dan keingintahuan saya sendiri. Ada beberapa video dan mentor yang juga saya miliki saat itu. Saya masih harus belajar banyak dan lebih banyak ruang untuk peningkatan saat saya membangun kurikulum pemrograman yang saya minati sendiri.
Setelah melihat ide-ide yang dimiliki Matplotlib dan komunitas untuk GSoD, saya merasa pengalaman ini akan menjadi pengalaman yang luar biasa untuk mengembangkan keterampilan saya sebagai penulis teknis dan mendapatkan kesempatan untuk belajar lebih banyak dari orang-orang di balik layar. Saya merasa proyek Matplotlib ini sangat bermakna dan merupakan sesuatu yang saya sukai dalam ideologi.
Untuk memperbaiki panduan penggunaan, tujuan saya sebagai penulis teknis adalah membantu pengguna menyelesaikan tugas yang mereka inginkan tanpa dibebani dengan fitur yang tersedia. Saya percaya bahwa dokumentasi terbaik akan terus berkembang dan beradaptasi dengan pengguna dan memungkinkan setiap pengguna untuk menavigasi ke solusi mereka sendiri.