Halaman ini diterjemahkan oleh Cloud Translation API.

Project Bokeh

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

Ringkasan proyek

Organisasi open source:: Bokeh
Penulis teknis:: vis_verborum
Nama proyek:: Membuat, membaca, membagikan: Mengoptimalkan dokumentasi Bokeh
Durasi proyek:: Durasi standar (3 bulan)

Project description

Membuat, membaca, berbagi: Mengoptimalkan dokumentasi Bokeh

1. Abstract

Bokeh adalah alat yang sangat canggih untuk membuat visualisasi interaktif berbasis browser dengan Python. Ini memiliki basis pengguna yang cukup besar (502 ribu unduhan conda bulanan, 855 ribu unduhan PyPi) dan sejumlah besar kontributor (455 kontributor di GitHub). Tidaklah mengherankan jika dokumentasi Bokeh yang luas dikembangkan secara organik. Dan dengan demikian, di beberapa tempat, tidak konsisten, sulit diakses, dan berbelit-belit.

Season of Docs dari Google memberikan kesempatan unik untuk peninjauan yang terfokus dan revisi struktur dan konten dokumentasi Bokeh - serta untuk memastikan bahwa dokumentasi serta alat dan alur kerja terkait sudah siap untuk menghadapi masa depan.

Saya telah membuat kode dan mendokumentasikan project open source dengan Python dan Sphinx (terbaru: PyZillow dan PyPresseportal). Namun, yang membuat saya menjadi peserta unik di Google's Season of Docs adalah latar belakang jurnalisme saya: saya bekerja di redaksi selama lebih dari 13 tahun, dengan bertahun-tahun sebagai editor pelaksana dan advokat perubahan digital. Selain tugas jurnalistik, saya memiliki tanggung jawab yang semakin meningkat dalam merancang dan mendokumentasikan panduan gaya dan alat digital baru, serta melatih staf redaksi.

Setelah pindah dari Eropa ke AS, saya memutuskan untuk mempelajari cara-cara baru dalam menyatukan antusiasme komunikasi dan coding. Menurut saya, penulisan teknis merupakan kombinasi optimal antara keterampilan dan pengalaman saya dalam menulis dan teknologi. Dalam proposal ini, saya akan menjabarkan bagaimana saya akan menggunakan Season Dokumen di Google untuk mengoptimalkan dokumentasi Bokeh: Dengan membuat pembuatan dan berkontribusi ke dokumentasi menjadi lebih praktis, dengan membuat membaca dokumentasi lebih mudah dan dengan mempermudah berbagi informasi dalam dokumentasi dengan orang lain.

2. Situasi saat ini

Dokumentasi resmi Bokeh terdiri dari unit-unit utama berikut:

Dokumentasi naratif: Panduan Penginstalan, Panduan Pengguna, Panduan Developer, Catatan Rilis
Galeri dan Demo (contoh interaktif dengan kode sumbernya)
Panduan Referensi (dokumentasi berdasarkan docstring)
Tutorial (koleksi Jupyter notebooks yang sangat banyak, dihosting di mybinder.org)
Bantuan model dan dokumen untuk IDE
Contoh dan README di repositori project

Selain itu, banyak informasi tersedia di forum dukungan Bokeh dan Stack Overflow, tempat pengembang Bokeh aktif menjawab pertanyaan pengguna, serta di blog Medium Bokeh.

Sebagian besar halaman dokumentasi dibuat dengan Sphinx, menggunakan beberapa ekstensi Sphinx standar dan kustom. Panduan Referensi, misalnya, dihasilkan dari dokumen yang menggunakan ekstensi seperti 'autodoc' dan 'bokeh_autodoc' kustom. Seperti halnya dokumentasi yang ditanam secara organik, panduan ini berisi redundansi dan inkonsistensi.

Salah satu hal pertama yang saya perhatikan ketika menganalisis dokumentasi yang ada adalah kurangnya pedoman gaya yang jelas untuk penulisan dokumentasi. Panduan Developer Bokeh berisi beberapa petunjuk dasar. Namun, dokumen ini tidak berisi banyak panduan tentang gaya, terutama yang berkaitan dengan dokumentasi yang lebih dari sekadar docstring. Akibatnya, masalah gaya dan struktural membuat akses informasi dalam dokumen menjadi lebih sulit, terutama bagi pengguna baru.

Contoh:

Penggunaan kata benda, gerund, dan kata-kata yang tidak umum, bukan kata kerja yang jelas dan kuat, akan membuat beberapa teks menjadi tidak perlu menjadi rumit: “Pengamatan utamanya adalah penggunaan umum melibatkan pembuatan objek plot dengan fungsi gambar()”. Ini harus ditata ulang agar pembacaan menjadi lebih mudah. Misalnya: "Fungsi gambar() adalah fungsi yang paling umum digunakan untuk membuat objek plot."
Beberapa kalimat sangat panjang, sehingga sulit dipahami: “Selanjutnya kita dapat menyebut vbar dengan daftar faktor nama buah sebagai koordinat x, tinggi batang sebagai koordinat atas, dan secara opsional setiap lebar atau properti lain yang ingin kita atur”. Kalimat yang lebih panjang harus dipecah menjadi kalimat yang lebih pendek atau daftar berbutir. Menyederhanakan kalimat akan sangat membantu bagi pengguna penyandang disleksia atau orang yang tidak menggunakan bahasa Inggris sebagai bahasa pertama mereka (lihat masalah #10160).
Penggunaan kata “Anda” dan “kami” tidak konsisten, yang membingungkan dan mengganggu: “Ada dua metode dasar yang dapat digunakan, bergantung pada kasus penggunaan Anda” dan “Kami dapat memetakan seluruh rangkaian tahun menggunakan panggilan terpisah” (dua contoh dari halaman yang sama). Beberapa halaman ditujukan kepada pembaca dengan cara yang bahkan berbeda-beda, seperti: “pengguna mungkin harus menginstal dependensi tambahan” atau “pengguna dapat membuat tata letak yang lebih kompleks”.
Kesalahan ketik, kata-kata yang hilang dan berlebihan, serta kesalahan tata bahasa memecah alur bacaan dan merusak kredibilitas informasi: “Bokeh memudahkan pembuatan diagram batang dasar” atau “Lihat bagian Glyphs di Panduan Pengguna”.
Inkonsistensi struktural dapat menjengkelkan bagi pembaca: Seperti memiliki contoh yang diberi anotasi dengan baik di satu halaman dan tidak ada penjelasan contoh di halaman lainnya.

Halaman landing dokumentasi Bokeh cukup pendek dan tidak menyertakan informasi tentang semua referensi yang tersedia (tidak menyebutkan koleksi lengkap tentang dokumen string dan fungsi bantuan model, forum dukungan, demo, atau blog Medium). Hal ini juga mempersulit pengguna baru untuk mulai menggunakan Bokeh.

3. Gol

Untuk memanfaatkan fase pengembangan dokumen selama sebelas minggu secara paling efisien, saya akan fokus pada tiga elemen utama:

3.1. Tingkatkan kualitas pembuatan dokumen

Sebagian besar dokumentasi Bokeh ditulis oleh kontributor yang menyertakan dokumentasi sebagai bagian dari permintaan pull untuk fungsi baru dan perbaikan bug. Meskipun saya akan menggunakan beberapa fase pengembangan dokumen untuk mengedit dan memfaktorkan ulang dokumen yang ada, saya akan menekankan pembuatan alur kerja untuk membuat dan mempertahankan dokumentasi agar siap menghadapi masa depan: Semudah mungkin bagi kontributor untuk menjaga standar dokumentasi yang tinggi secara konsisten.

Kami akan memastikan hal ini dengan dua pendekatan:

Saya akan membuat serangkaian pedoman gaya yang praktis dan sederhana untuk disertakan dalam Panduan Developer yang ada. Panduan ini akan membahas gaya, tata bahasa, dan struktur. Selain itu, saya akan menggunakan saluran komunikasi internal seperti Slack untuk memastikan kontributor Bokeh mengetahui pedoman gaya. Saya juga akan menawarkan pelatihan pribadi dan sesi Tanya Jawab untuk tim.
Saya akan bekerja dengan tim inti untuk mencari serangkaian alat optimal untuk kendali mutu dokumentasi, yang akan ditambahkan ke alur kerja Bokeh yang ada untuk PR (permintaan pull) dan CI (continuous integration). Bergantung pada persyaratan tim, hal ini dapat berarti menambahkan alat seperti pydocstyle, proselint, atau pemeriksaan ejaan sphinxcontrib-spelling ke rangkaian pengujian Bokeh, penyiapan pra-commit, atau tindakan GitHub. Saya telah menambahkan bukti konsep yang berfungsi ke tindakan GitHub dari salah satu project open source saya sendiri.

3.2. Tingkatkan kemampuan membaca dokumen

Tujuan dari dokumentasi yang baik adalah untuk memudahkan pengguna saat ini dan calon pengguna untuk menemukan informasi yang benar-benar tepat dan dapat menggunakan informasi ini seefisien mungkin.

Faktor utama untuk {i>usability <i}teks adalah gaya dan strukturnya: Menulis dokumentasi dengan gaya yang jelas dan konsisten memungkinkan pembaca untuk mengambil informasi dengan cepat, tanpa gangguan dan bahasa yang berlebihan. Struktur dokumentasi yang lugas dan transparan memudahkan Anda menemukan informasi yang relevan dengan cepat.

Saya akan fokus pada kedua bidang itu, dengan penekanan pada kegunaan bagi pengguna baru. Hal ini akan mencakup peninjauan dokumentasi narasi yang menyeluruh, yang berpusat pada Panduan Pengguna. Saya juga akan memperbaiki halaman landing dokumentasi untuk menangani berbagai target audiens dengan lebih jelas dan memastikan setiap pengguna dapat menemukan referensi yang tepat dengan cepat.

Sama seperti peningkatan pembuatan dokumen yang diuraikan di atas, saya akan fokus untuk meletakkan dasar bagi peningkatan di masa mendatang dan standar yang tinggi untuk dokumentasi Bokeh.

3.3. Meningkatkan kualitas berbagi dokumen

Diskusi seputar Bokeh semakin sering terjadi di platform pihak ketiga. Banyak dari platform ini menggunakan metadata seperti OpenGraph Facebook untuk menyertakan pratinjau link yang lengkap. OpenGraph digunakan oleh layanan seperti Facebook, Twitter, LinkedIn, Slack, dan iMessage. Forum Bokeh’s Discourse juga menggunakan OpenGraph untuk merender pratinjau link.

Untuk memanfaatkan teknologi ini, saya akan menambahkan metadata ke halaman web buatan Sphinx Bokeh, seperti yang dijelaskan dalam masalah #9792. Cara yang paling efisien adalah menggunakan ekstensi Sphinx khusus. Beberapa hari yang lalu, versi pertama ekstensi Sphinx untuk data OpenGraph dipublikasikan di GitHub. Saya akan menggunakan beberapa fase pengembangan dokumen untuk membantu meningkatkan ekstensi ini agar dapat digunakan dengan dokumentasi Bokeh.

Saya juga telah membuat bukti konsep yang berhasil saya gunakan dalam salah satu project open source saya, PyPresseportal. Ekstensi ini otomatis mengumpulkan informasi yang relevan seperti judul, deskripsi, gambar, dan URL. Kemudian, kode ini menyisipkan informasi ini ke dalam kode HTML yang dihasilkan Sphinx sebagai tag OpenGraph.

Langkah berikutnya dalam mengembangkan ekstensi ini adalah memperkenalkan perintah khusus untuk menentukan metadata OpenGraph secara manual (serupa dengan perintah 'meta' docutil yang ada). Metadata yang dibuat secara otomatis hanya akan digunakan sebagai penggantian jika tidak ada data yang dimasukkan secara manual.

Mendukung Data Terstruktur jauh lebih kompleks, jadi saya akan fokus terutama pada penyertaan metadata OpenGraph berkualitas tinggi untuk dokumentasi Bokeh. Semua pekerjaan yang diperlukan untuk mendukung OpenGraph akan, di saat yang sama, menjadi fondasi bagi dukungan Data Terstruktur.

Anggota komunitas Sphinx dan ReadTheDocs telah menyatakan minat dalam mengembangkan ekstensi untuk OpenGraph dan Data Terstruktur (misalnya masalah #1758 dan #5208), dan saya akan memastikan untuk bekerja sama dengan mereka secara erat.

4. Hasil

Ringkasnya, berikut hasil yang saya harapkan dari Season Dokumen:

Pedoman gaya dokumentasi untuk kontributor Bokeh
Merevisi alur kerja PR dan CI untuk menyertakan pengendalian kualitas dokumentasi otomatis
Panduan Pengguna yang telah diedit dan disusun ulang
Halaman landing dokumentasi yang direvisi
Metadata OpenGraph disertakan dalam halaman web dokumentasi dan ekstensi Sphinx yang berfungsi

Selain itu, saya juga akan menyimpan “doclog” untuk mendokumentasikan perjalanan saya melalui Season of Docs di Google di situs/Medium atau blog Bokeh Medium milik saya. Hal ini juga akan berfungsi sebagai dasar untuk laporan proyek untuk Google. Saya akan melakukan semua pekerjaan secara transparan, dalam bentuk masalah GitHub dan permintaan pull, jika memungkinkan.

5. Rentang waktu

Sebelum fase ikatan komunitas: Saya sudah aktif berpartisipasi dalam beberapa diskusi tentang repositori GitHub Bokeh serta telah menghubungi Bryan Van de Ven dan Pavithra Eswaramoorthy, mentor Bokeh untuk Google's Season of Docs. Saya akan tetap aktif dalam percakapan tentang Bokeh dan juga akan lebih membiasakan diri dengan Bokeh dengan membangun dan mempublikasikan visualisasi.

Fase ikatan komunitas (17/08 - 13/09):

Kenali tim inti, perbaiki rencana proyek dengan bertukar pikiran dengan mentor
Siapkan jadwal dan saluran komunikasi untuk pelaporan dan masukan rutin dengan mentor
Aktiflah di Slack Bokeh untuk memberi tahu semua kontributor Bokeh yang tertarik tentang Season of Docs dari Google dan target untuk fase pengembangan dokumen
Mengumpulkan masukan dari kontributor Bokeh untuk lebih menyempurnakan rencana fase pengembangan dokumen

Tahap pengembangan dokumen

Minggu 1, 14/09 - 20/09:

Mulai mengaudit dan mengedit dokumentasi narasi
Mulai membuat draf panduan gaya

Minggu ke-2, 09/21 - 27/09:

Terus kerjakan panduan gaya
Lanjutkan pengeditan dokumentasi narasi
Mulai merombak halaman landing dokumentasi

Minggu ke-3, 28/09 - 04/10:

Menyelesaikan panduan gaya
Menyelesaikan halaman landing dokumentasi

Minggu 4, 10/05 - 10/11:

Menyelesaikan pengeditan dokumentasi narasi
Berdiskusi dengan tim inti Bokeh tentang mengintegrasikan alat untuk pengendalian kualitas dokumen dalam alur kerja PR/CI

Minggu 5, 12/10 - 18/10:

Siapkan sesi Tanya Jawab dengan kontributor Bokeh di Slack untuk membahas pedoman gaya, peningkatan pada dokumentasi narasi, dan alur kerja PR/CI
Mulai mengembangkan bukti konsep yang sudah ada untuk metadata OpenGraph ke dalam ekstensi Sphinx yang dapat di-deploy
Merevisi pedoman gaya berdasarkan masukan dari sesi Tanya Jawab bersama kontributor Bokeh

Minggu 6, 19/10 - 25/10:

Mulai pengujian alat untuk pengendalian kualitas dokumen dalam alur kerja PR dan CI
Melanjutkan pengembangan ekstensi Sphinx untuk metadata

Minggu ke-7, 26/10 - 01/11:

Pengujian ekstensi Sphinx
Sesi Tanya Jawab kedua dengan kontributor Bokeh di Slack
Merevisi hasil kerja berdasarkan masukan dari sesi Tanya Jawab kedua

Minggu ke-8, 02/11 - 08/11:

Men-deploy ekstensi Sphinx dan memublikasikan dokumentasi naratif yang lebih baik serta halaman landing dokumentasi

Minggu 9, 9/11 - 15/11:

Men-deploy alat kendali mutu dokumen ke dalam alur kerja PR dan CI
Memperbarui dan memublikasikan Panduan Developer untuk menyertakan panduan gaya serta penambahan alur kerja PR dan CI

Minggu 10, 16/11 - 22/11:

Selesaikan tugas yang tersisa

Minggu 11, 23/11 - 29/11:

Mulai menulis laporan proyek
Mulai menulis evaluasi proyek

Fase finalisasi proyek

Minggu 12, 30/11 - 05/12:

Finalisasi dan penyerahan laporan proyek

Minggu 13, 12/03 - 12/10:

Finalisasi dan kirim evaluasi proyek

Setelah selesainya Season Google Dokumen:

Saya berharap dapat terus terlibat dalam pengembangan Bokeh dan terus mengerjakan dokumentasi Bokeh.
Saya berencana melanjutkan pengembangan ekstensi Sphinx untuk metadata OpenGraph/Structured Data.
Saya berharap dapat menggunakan latar belakang jurnalisme dan jaringan yang ada untuk mempromosikan Bokeh sebagai alat dalam jurnalisme data. Misalnya, dengan menulis tentang Bokeh dengan mempertimbangkan audiens jurnalistik atau dengan menawarkan diskusi konferensi tentang penggunaan Bokeh dalam konteks jurnalistik.

6. Tentang diri saya

Saya awalnya adalah seorang jurnalis, dengan latar belakang di bidang berita TV, online, dan radio. Bekerja sebagai redaktur pelaksana dan reporter di TV dan berita digital telah memberi saya pengalaman bertahun-tahun dalam menulis dan mengedit. Pada saat yang sama, saya mengerjakan beberapa project yang mempromosikan transformasi dan otomatisasi digital. Saya menulis banyak panduan yang mencakup alat dan alur kerja digital, serta panduan gaya dan strategi komunikasi untuk brand berita digital. Saya juga melatih anggota tim untuk menggunakan alat-alat tersebut.

Saya selalu tertarik pada persimpangan antara komunikasi dan teknologi. Dunia yang benar-benar baru terbuka bagi saya ketika saya belajar coding dengan Python: Misalnya, saya dapat melakukan analisis dan visualisasi data untuk jurnalisme data. Dengan mempelajari coding, saya juga dapat aktif bekerja sama dengan software engineer guna mengembangkan alat digital untuk alur kerja redaksi.

Sayangnya, manual dan dokumen yang saya tulis di pekerjaan saya sebelumnya bersifat non-publik. Oleh karena itu, sekarang saya berfokus untuk lebih terlibat dengan project open source (lihat contoh di bawah). Saya mendasarkan pekerjaan saya di bidang penulisan teknis pada panduan gaya seperti panduan gaya dokumentasi developer Google dan panduan gaya Microsoft. Saya rutin menggunakan GitHub, Slack, dan Linux. Saya telah menulis dokumentasi naratif serta docstring dan petunjuk tulisan, menggunakan alat seperti autodoc Sphinx, Mypy, dan Sphinx.

Saat ini saya bekerja {i>freelance<i}. Jadwal saya memberikan fleksibilitas yang diperlukan untuk mengerjakan dokumentasi Bokeh sekitar 25 jam per minggu selama fase pengembangan dokumen. Saya bekerja di Zona Waktu Pasifik, tetapi saya senang dapat mengakomodasi jadwal dan kebutuhan tim.

7. Contoh dokumentasi open source terbaru

PyZillow: PyZillow adalah wrapper Python untuk API situs properti Zillow.com. Selain memberikan beberapa kode dan bertindak sebagai salah satu pengelola kode, saya menulis dokumentasi lengkap. Saya menggunakan Sphinx untuk dokumentasi naratif, serta untuk referensi modul. Saya membuat referensi modul dengan autodoc ekstensi Sphinx, berdasarkan docstring yang saya tambahkan ke kode.
PyPresseportal: PyPresseportal adalah wrapper Python untuk API website presseportal.de. Situs presseportal.de adalah salah satu distributor terbesar untuk siaran pers dan pengumuman hubungan investor di Jerman. Misalnya, hampir semua polisi dan pemadam kebakaran menggunakan layanan ini untuk mendistribusikan siaran pers mereka. Setelah menggunakan API selama bertahun-tahun sebagai jurnalis, saya memutuskan untuk mengembangkan antarmuka Python guna mengakses sumber data situs yang luas sebagai objek Python. Saya menulis kode itu dan seluruh dokumentasi berbasis Sphinx.