Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season 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 meliputi pembuatan konten yang membantu memperkenalkan Matplotlib kepada pengguna baru. Untuk Mengembangkan Jalur Masuk Matplotlib, saya mengusulkan pendekatan alternatif untuk dokumentasi saat ini. Saya seorang penulis teknis baru di industri ini, tetapi latar belakang saya adalah di bidang pendidikan dan pendidikan. Penulisan teknis dan edukasi memiliki kemiripan yang kuat dengan fokus pada pembuatan konten yang penuh empati dan memungkinkan pengguna untuk menyelesaikan tugas mereka dengan sumber daya 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. Keduanya 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, kami menunjukkan pemahaman tentang lingkungan tempat pengguna bekerja. Hal ini meningkatkan hubungan dokumentasi dan pengguna dalam hal pencapaian tujuan atau ekspektasi penyelesaian tugas.
Pengguna memiliki tujuan turunan yang konsisten. Misalnya, data scientist di perusahaan sepatu harus menyajikan data pelanggan kepada tim untuk menggambarkan tren belanja dari waktu ke waktu. Dalam situasi ini, pengguna harus belajar menavigasi Matplotlib dan memanfaatkan alat dalam {i>library<i} untuk menyelesaikan tugas yang ada.
Dengan konteks tambahan untuk mendukung dokumentasi, pengguna baru mungkin akan lebih mampu mengenali topik tersebut. Tujuan turunan pengguna paralel dengan dokumentasi. Saya berharap untuk 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 untuk pengguna, untuk melalui dan pada dasarnya menulis buku 'Intro to Matplotlib' sepanjang 200 halaman, dan menjadikannya entri utama ke dokumen."
Pendekatan Alternatif Penulisan Ekspositori
Dokumentasi saat ini menunjukkan fitur Matplotlib, yaitu hal-hal yang dapat dilakukan pengguna dengan library. Misalnya, tutorial sering kali mengikuti pola yang tidak menjelaskan metode yang mendasarinya.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
Sering kali dengan dokumentasi dan dukungan pemrograman, pengguna disarankan untuk menjalankan kode sendiri untuk memahami apa yang terjadi. Meskipun pola pikir pemrograman meningkatkan pemahaman pengguna tentang topik, kurva pembelajaran untuk transformasi hanya memiliki sedikit konten pendukung. Ini bisa menjadi tantangan yang berat karena dokumentasi terbatas.
Menyediakan diagram, gambar, atau visual tambahan akan membantu menciptakan peluang pembelajaran baru. Struktur di bawah ini juga akan berfungsi sebagai template untuk konten baru. Selain itu, menambahkan gambar atau grafis non-tekstual dapat memperoleh manfaat dari fitur seperti info dan pelatihan. Ada kalanya gambar lebih sulit dijelajahi tanpa indikasi tentang bagaimana atau di mana kode diubah menjadi output yang dieksekusi. Saya yakin bahwa ada elemen visual yang kuat yang dapat menumbuhkan pemahaman yang lebih baik tentang topik tersebut.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
Ada potensi besar dalam pendekatan alternatif penggunaan penulisan ekspositori untuk dokumentasi. Dengan melihat berbagai konsep untuk transformasi, pengguna akan dapat mengidentifikasi dengan lebih baik strategi dasar dari pengembangan visualisasi ke data. Pengetahuan ini dapat membantu pengguna berinovasi dan memanfaatkan fitur seperti yang diberikan melalui contoh yang didasarkan pada kasus penggunaan yang realistis.
Seiring dengan semakin populernya Matplotlib, konsistensi dalam kemudahan penggunaan dan kedekatan adalah bukti reputasi perpustakaan ini. Karakteristik ini dapat menunjukkan pola dan strategi umum yang dapat muncul tidak hanya dalam kode, tetapi juga dalam dokumentasi. Jika Matplotlib bersifat sederhana dan standar bagi pengguna untuk diprogram, seperti yang terlihat dalam penggunaannya yang terus berkembang dan sumber daya yang berkembang, Matplotlib juga bisa menjadi cara untuk dokumentasi teknis.
Saat pengguna mengalami masalah, biasanya menggunakan penelusuran untuk menyelesaikannya. Daripada mengandalkan penelusuran sebagai metode navigasi utama, akan lebih berdampak jika pengguna membuat kurikulum mereka sendiri dalam dokumentasi. Dalam hal ini, pengguna mencari solusi untuk masalah mereka, lalu ketika mereka mengalami 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 kaya ke afinitas subjek serta topik informasi akan membantu membangun jaringan yang efektif. Melalui jaringan ini, pengguna akan cenderung terus menggunakan dokumentasi saat mereka menavigasi ke topik mereka dan menjelajahi lebih banyak informasi terkait dengan topik tersebut.
Hambatan
Selalu ada tantangan dalam proyek yang sekomprehensif dan sedetail ini. Sebagai penulis teknis baru di industri ini, saya memiliki pengalaman terbatas dalam menggunakan Sphinx dan ReST untuk menulis dokumentasi. Saya juga masih pemula jika menyangkut Matplotlib dan Git. Diperlukan waktu untuk menangani keempat sistem ini dan membiasakan diri menggunakannya untuk kolaborasi dan penelitian. Saya perlu mendelegasikan waktu selama fase ikatan komunitas dan lebih awal untuk membangun fondasi yang diperlukan untuk jalur level pemula. Selama jangka waktu ini, jika ada masalah dengan konsep dan dasar, saya perlu menghubungi komunitas untuk mendapatkan dukungan tambahan.
Mengkoordinasikan upaya kolaboratif di seluruh zona waktu dan melalui platform online juga akan memerlukan beberapa penyesuaian. Ada berbagai cara komunikasi yang digunakan orang-orang di seluruh industri, jadi ini adalah masalah untuk memastikan saya dapat diakses dan didekati di semua media. Saya akan bersikap transparan dalam menentukan prioritas dari berbagai ekspektasi secara keseluruhan. Meskipun saya baru saja memulai pekerjaan seperti ini di industri ini, saya berinvestasi untuk membuat diri saya bertanggung jawab dan terbuka terhadap masukan dan kritik. Saya merasa kualitas ini sangat berharga di bidang mana pun.
Selain itu, meningkatkan pengujian {i>usability<i} adalah bagian dari dokumentasi yang menurut saya akan menguntungkan jalur masuk Matplotlib. Melakukan survei untuk kegunaan terkait konten bertujuan untuk menyediakan profil pengguna, yaitu persona. Informasi seperti pengalaman pengguna, industri mereka, dan riwayat pemecahan masalah sangatlah berharga. Potongan-potongan ini membantu membentuk bahasa di balik prosedur. Saat menulis memenuhi kebutuhan pembaca di tingkat mereka, konten menjadi lebih matang, bukan hanya sebagai instruksi.
Perjuangan besar sering kali terletak pada pembuatan praktik pengujian kegunaan yang berkelanjutan. Sangatlah umum untuk memiliki satu instance pengujian, jika dilakukan, selama pengembangan konten. Pengujian kegunaan rutin membantu meningkatkan narasi konten. Saya berharap untuk mengatur jadwal atau melakukan tes {i>usability<i} berulang dengan komunitas Matplotlib.
Kesimpulan
Saya memiliki sedikit pengalaman menggunakan Python dan Matplotlib di waktu luang saya. Materi yang telah saya pelajari sendiri selama beberapa bulan terakhir adalah dengan dukungan dokumentasi saat ini dan keingintahuan saya sendiri. Ada beberapa video dan mentor yang saya miliki juga pada saat itu. Saya masih harus belajar banyak dan bahkan lebih banyak untuk perbaikan saat saya membangun kurikulum pemrograman yang saya minati sendiri.
Setelah melihat ide yang dimiliki Matplotlib dan komunitas untuk GSoD, saya merasa itu akan menjadi pengalaman yang luar biasa untuk meningkatkan 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 menjadi sesuatu yang saya sukai dalam ideologi.
Untuk mengerjakan perombakan panduan penggunaan, tujuan saya sebagai penulis teknis adalah membantu pengguna menyelesaikan tugas yang mereka inginkan tanpa kewalahan dengan fitur yang tersedia. Saya percaya bahwa dokumentasi terbaik akan terus tumbuh dan beradaptasi dengan pengguna dan memungkinkan setiap pengguna untuk menavigasi ke solusi mereka sendiri.