Halaman ini diterjemahkan oleh Cloud Translation API.

Project Matplotlib

Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.

Ringkasan proyek

Organisasi open source:: Matplotlib
Penulis teknis:: jeromev
Nama project:: Mengembangkan Jalur Entri Matplotlib
Durasi project:: Durasi standar (3 bulan)

Project description

Pengantar

Saran project Matplotlib untuk Google Season of Docs 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 adalah penulis teknis baru di industri ini; namun, latar belakang saya adalah pendidikan dan bidang yang terkait dengan 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 mendapatkan manfaat dari peningkatan untuk berempati dengan pengguna baru. Sebagian besar materi saat ini terdiri dari data acak dan visual tanpa label. Fungsi ini sangat cocok untuk menampilkan visual dan fitur Matplotlib dengan cepat. Namun, untuk kasus penggunaan seseorang yang baru menggunakan Matplotlib, akan sulit untuk menelusuri transformasi data menjadi visual.

Konteks dalam pendekatan ekspositori adalah solusi untuk kendala ini. Dengan menulis prosedur melalui lensa contoh dunia nyata, kita menunjukkan pemahaman tentang lingkungan tempat pengguna bekerja. Hal ini meningkatkan hubungan antara dokumentasi dan pengguna dalam hal mencapai sasaran atau ekspektasi untuk menyelesaikan tugas.

Seorang pengguna memiliki tujuan turunan yang konsisten. Misalnya, seorang data scientist di sebuah perusahaan sepatu harus mempresentasikan data pelanggan kepada sebuah tim untuk mengilustrasikan tren belanja dari waktu ke waktu. Dalam situasi ini, pengguna harus mempelajari cara menavigasi Matplotlib dan memanfaatkan alat dalam library untuk menyelesaikan tugas yang ada.

Dengan konteks tambahan untuk mendukung dokumentasi, pengguna baru mungkin lebih dapat mengenali topik tersebut. Tujuan turunan pengguna sejajar dengan dokumentasi. Saya berharap dapat bekerja menuju 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 bagi pengguna, untuk melalui dan pada dasarnya menulis buku 'Intro to Matplotlib' sepanjang 200 halaman, dan menjadikannya entri utama ke dokumen."

Pendekatan Alternatif Penulisan Ekspositoris

Dokumentasi saat ini menunjukkan fitur Matplotlib, yaitu hal-hal yang dapat dilakukan pengguna dengan library. 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 dokumentasi dan dukungan pemrograman, pengguna direkomendasikan 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 bisa menjadi tantangan yang luar biasa karena dokumentasi yang terbatas.

Menyediakan diagram, gambar, atau visual lainnya akan membantu menciptakan peluang belajar baru. Struktur di bawah ini juga akan berfungsi dengan baik sebagai template untuk konten baru. Selain itu, tujuan menambahkan gambar atau grafik non-tekstual dapat dioptimalkan dengan fitur seperti info dan tanda panduan. Terkadang gambar lebih sulit dinavigasi tanpa indikasi bagaimana atau di mana kode diubah menjadi output yang dieksekusi. Saya yakin bahwa ada elemen visual yang kuat yang hilang dan dapat mendorong 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 ini menggunakan penulisan ekspositori untuk dokumentasi. Dengan melihat berbagai konsep untuk transformasi, pengguna akan dapat mengidentifikasi strategi yang mendasari pengembangan visualisasi data dengan lebih baik. Pengetahuan ini dapat membantu pengguna berinovasi dan memanfaatkan fitur seperti yang disajikan oleh contoh berdasarkan kasus penggunaan yang realistis.

Seiring dengan semakin populernya Matplotlib, konsistensi dalam kemudahan penggunaan dan kemudahan pendekatan adalah bukti reputasi perpustakaan ini. Karakteristik ini dapat digunakan untuk menunjukkan pola dan strategi umum yang dapat muncul tidak hanya dalam kode, tetapi juga dalam dokumentasi. Jika Matplotlib mudah dan standar bagi pengguna untuk diprogram, seperti yang terlihat dari penggunaannya yang semakin meningkat dan resource yang diperluas, hal ini juga dapat berlaku untuk dokumentasi teknis.

Saat pengguna mengalami masalah, mereka biasanya menggunakan penelusuran untuk mengatasinya. Daripada mengandalkan penelusuran sebagai metode navigasi utama, akan lebih efektif jika pengguna membuat kurikulum mereka sendiri dalam dokumentasi. Dalam hal ini, pengguna akan menelusuri solusi untuk masalah mereka, lalu saat mereka mengalami masalah lain atau menginginkan informasi tambahan, mereka akan menggunakan link yang disematkan dan menyeluruh di seluruh situs.

Hal ini akan melibatkan arsitektur bottom-up dalam sistem organisasi. Untuk setiap topik dalam Matplotlib, jaringan tautan yang kaya ke afinitas subjek serta topik informasi akan membantu membangun jaringan yang kuat. Di seluruh jaringan ini, pengguna akan lebih cenderung untuk terus menggunakan dokumentasi saat mereka membuka topik dan menjelajahi lebih banyak informasi yang terkait dengan topik tersebut.

Hambatan

Selalu ada tantangan dengan proyek sekomprehensif dan sedetail ini. Sebagai penulis teknis yang baru di industri ini, saya memiliki pengalaman terbatas dalam menggunakan Sphinx dan ReST untuk menulis dokumentasi. Saya juga seorang pemula dalam hal Matplotlib dan juga Git. Menangani keempat sistem ini dan menggunakannya untuk kolaborasi dan riset akan membutuhkan waktu. Saya harus mendelegasikan waktu selama fase ikatan komunitas dan sebelumnya untuk membangun fondasi yang diperlukan bagi jalur tingkat pemula. Selama periode ini, jika saya mengalami masalah terkait konsep dan dasar-dasarnya, saya perlu menghubungi komunitas untuk mendapatkan dukungan tambahan.

Koordinasi upaya kolaboratif di seluruh zona waktu dan melalui platform online juga akan memerlukan penyesuaian. Ada berbagai saluran komunikasi yang digunakan orang-orang di seluruh industri, jadi saya harus memastikan bahwa saya dapat diakses dan didekati di semua media. Saya akan bersikap transparan dalam menentukan prioritas berbagai ekspektasi. Meskipun saya baru saja mulai mengambil pekerjaan seperti ini di industri ini, saya berkomitmen untuk bertanggung jawab dan terbuka terhadap masukan dan kritik. Saya merasa kualitas ini sangat berharga, apa pun bidangnya.

Selain itu, meningkatkan pengujian kegunaan adalah bagian dari dokumentasi yang saya yakin akan bermanfaat bagi jalur entri Matplotlib. Melakukan survei kegunaan terkait konten bertujuan untuk memberikan profil pengguna, yaitu persona. Informasi seperti pengalaman pengguna, industrinya, dan histori pemecahan masalah sangat berharga. Bagian-bagian ini membantu membentuk bahasa di balik prosedur. Jika tulisan sesuai dengan tingkat pembaca, konten akan menjadi lebih matang dan tidak hanya berfungsi sebagai petunjuk.

Kesulitan besar sering kali terletak pada pembuatan 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 menyiapkan jadwal atau melakukan pengujian kegunaan berulang dengan komunitas Matplotlib.

Kesimpulan

Saya memiliki sedikit pengalaman menggunakan Python dan Matplotlib di waktu luang saya. Jumlah yang telah saya pelajari sendiri selama beberapa bulan terakhir adalah dengan dukungan dokumentasi saat ini dan rasa ingin tahu saya sendiri. Ada juga beberapa video dan mentor yang saya miliki pada saat itu. Saya masih harus banyak belajar dan bahkan ada banyak hal yang bisa ditingkatkan saat saya membuat kurikulum pemrograman saya sendiri yang saya minati.

Setelah melihat ide-ide yang dimiliki Matplotlib dan komunitas untuk GSoD, saya merasa ini akan menjadi pengalaman yang sangat baik untuk meningkatkan keterampilan saya sebagai penulis teknis dan mendapatkan kesempatan untuk belajar lebih banyak dari orang-orang di balik layar. Saya merasa bahwa project Matplotlib ini bermakna dan merupakan sesuatu yang saya minati dalam ideologi.

Untuk mengerjakan perombakan panduan penggunaan, sasaran 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 berkembang dan beradaptasi dengan pengguna serta memungkinkan pengguna untuk membuka solusi mereka sendiri.