Halaman ini diterjemahkan oleh Cloud Translation API.

Project Bokeh

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

Ringkasan proyek

Organisasi open source:: Bokeh
{i>Technical writer <i}(Penulis teknis):: vis_verborum
Nama proyek:: Membuat, membaca, berbagi: Mengoptimalkan dokumentasi Bokeh
Durasi project:: Durasi standar (3 bulan)

Project description

Membuat, membaca, berbagi: Mengoptimalkan dokumentasi Bokeh

1. Abstrak

Bokeh adalah alat yang sangat canggih untuk membuat visualisasi berbasis browser yang interaktif dengan Python. Conda memiliki basis pengguna yang cukup besar (502 ribu download conda bulanan, 855 ribu download PyPi) dan sejumlah besar kontributor (455 kontributor di GitHub). Tidak mengherankan jika dokumentasi Bokeh yang luas berkembang secara organik. Oleh karena itu, di beberapa tempat, tidak konsisten, sulit diakses, dan berbelit-belit.

Season of Docs Google memberikan peluang unik untuk peninjauan dan revisi yang terfokus pada struktur dan konten dokumentasi Bokeh - serta untuk memastikan bahwa dokumentasi dan alat serta alur kerja terkait siap untuk masa mendatang.

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

Setelah pindah dari Eropa ke Amerika Serikat baru-baru ini, saya memutuskan untuk mempelajari cara baru untuk menggabungkan antusiasme saya terhadap komunikasi dan coding. Saya menemukan bahwa penulisan teknis adalah kombinasi optimal dari keterampilan dan pengalaman saya dalam menulis dan teknologi. Dalam proposal ini, saya akan menjelaskan cara menggunakan Season of Docs Google untuk mengoptimalkan dokumentasi Bokeh: Dengan membuat pembuatan dan kontribusi pada dokumentasi lebih mudah, dengan membuat pembacaan dokumentasi lebih mudah, dan dengan membuat berbagi informasi dalam dokumentasi dengan orang lain lebih mudah.

2. Situasi saat ini

Dokumentasi resmi Bokeh terdiri dari unit utama berikut:

Dokumentasi narasi: Panduan Penginstalan, Panduan Pengguna, Panduan Developer, Catatan Rilis
Galeri dan Demo (contoh interaktif dengan kode sumbernya)
Panduan Referensi (dokumentasi berdasarkan docstring)
Tutorial (koleksi lengkap notebook Jupyter, dihosting di mybinder.org)
Docstring dan bantuan model untuk IDE
Contoh dan README di repositori project

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

Sebagian besar halaman web dokumentasi dibuat dengan Sphinx, menggunakan beberapa ekstensi Sphinx standar dan kustom. Misalnya, Panduan Referensi dibuat dari docstring, menggunakan ekstensi seperti 'autodoc' dan 'bokeh_autodoc' kustom. Seperti sifat dokumentasi yang berkembang secara organik, dokumentasi ini berisi redundansi dan inkonsistensi.

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

Contoh:

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

Halaman landing dokumentasi Bokeh agak pendek dan tidak menyertakan informasi tentang semua referensi yang tersedia (tidak menyebutkan library docstring dan fungsi bantuan model yang luas, forum dukungan, demo, atau blog Medium). Hal ini juga mempersulit pengguna baru untuk memulai Bokeh.

3. Sasaran

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

3.1. Tingkatkan 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 yang tahan lama: Kontributor harus dapat mempertahankan standar dokumentasi yang tinggi secara konsisten dengan semudah mungkin.

Saya 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 bahwa kontributor Bokeh mengetahui panduan gaya. Saya juga akan menawarkan pelatihan satu lawan satu dan sesi Tanya Jawab untuk tim.
Saya akan bekerja sama dengan tim inti untuk menemukan serangkaian alat untuk kontrol kualitas dokumentasi yang optimal, yang akan ditambahkan ke alur kerja Bokeh yang ada untuk PR (permintaan pull) dan CI (integrasi berkelanjutan). Bergantung pada persyaratan tim, hal ini dapat berarti menambahkan alat seperti pydocstyle, proselint, atau sphinxcontrib-spelling untuk pemeriksaan ejaan ke suite pengujian Bokeh, penyiapan pra-commit, atau tindakan GitHub. Saya telah menambahkan bukti konsep yang berfungsi ke tindakan GitHub salah satu project open source saya.

3.2. Meningkatkan kualitas membaca dokumen

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

Faktor utama untuk kegunaan 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 sederhana dan transparan memudahkan Anda menemukan informasi yang relevan dengan cepat.

Saya akan fokus pada kedua area tersebut, dengan penekanan pada kegunaan untuk pengguna baru. Hal ini akan mencakup peninjauan menyeluruh terhadap dokumentasi narasi, yang berfokus pada Panduan Pengguna. Saya juga akan merombak halaman landing dokumentasi untuk lebih jelas menjangkau berbagai target audiens dan memastikan setiap pengguna dapat menemukan referensi yang tepat dengan cepat.

Sama seperti meningkatkan pembuatan dokumen yang diuraikan di atas, saya akan berfokus pada meletakkan fondasi untuk peningkatan di masa mendatang dan standar yang terus tinggi untuk dokumentasi Bokeh.

3.3. Tingkatkan kualitas berbagi dokumen

Semakin banyak diskusi seputar Bokeh yang terjadi di platform pihak ketiga. Banyak platform ini menggunakan metadata seperti OpenGraph Facebook untuk menyertakan pratinjau lengkap link. OpenGraph digunakan oleh layanan seperti Facebook, Twitter, LinkedIn, Slack, dan iMessage. Forum Discourse Bokeh juga menggunakan OpenGraph untuk merender pratinjau link.

Untuk memanfaatkan teknologi ini, saya akan menambahkan metadata ke halaman web yang dibuat oleh Sphinx dari 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 di salah satu project open source saya sendiri, PyPresseportal. Ekstensi ini otomatis mengumpulkan informasi yang relevan seperti judul, deskripsi, gambar, dan URL. Kemudian, informasi ini disisipkan ke dalam kode HTML yang dihasilkan Sphinx sebagai tag OpenGraph.

Langkah berikutnya dalam mengembangkan ekstensi ini adalah memperkenalkan perintah kustom untuk menentukan metadata OpenGraph secara manual (mirip dengan perintah 'meta' yang ada di docutil). 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 mendukung OpenGraph, pada saat yang sama, akan meletakkan dasar untuk dukungan Data Terstruktur.

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

4. Hasil

Sebagai ringkasan, berikut adalah hasil yang saya harapkan dari Season of Docs:

Panduan gaya dokumentasi untuk kontributor Bokeh
Alur kerja PR dan CI yang telah direvisi untuk menyertakan kontrol kualitas dokumentasi otomatis
Panduan Pengguna yang diedit dan disusun ulang
Halaman landing dokumentasi yang direvisi
Metadata OpenGraph yang disertakan di halaman web dokumentasi dan ekstensi Sphinx yang berfungsi

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

5. Linimasa

Sebelum fase ikatan komunitas: Saya sudah berpartisipasi secara aktif dalam beberapa diskusi di repositori GitHub Bokeh dan telah menghubungi Bryan Van de Ven dan Pavithra Eswaramoorthy, mentor Bokeh untuk Season of Docs Google. Saya akan tetap aktif dalam percakapan tentang Bokeh dan juga akan lebih memahami Bokeh dengan membuat dan memublikasikan visualisasi.

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

Mengenali tim inti, meningkatkan kualitas rencana project dengan berdiskusi dengan mentor
Menyiapkan jadwal dan saluran komunikasi untuk pelaporan dan masukan rutin dengan mentor
Aktif di Slack Bokeh untuk memberi tahu semua kontributor Bokeh yang tertarik tentang Season of Docs Google dan sasaran untuk fase pengembangan dokumen
Kumpulkan masukan dari kontributor Bokeh untuk lebih menyempurnakan rencana fase pengembangan dokumen

Fase pengembangan dokumen

Minggu ke-1, 14/09 - 20/09:

Mulai mengaudit dan mengedit dokumentasi narasi
Mulai membuat draf pedoman gaya

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

Melanjutkan pekerjaan pada pedoman gaya
Melanjutkan pengeditan dokumentasi narasi
Mulai merombak halaman landing dokumentasi

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

Menyelesaikan pedoman gaya
Menyelesaikan halaman landing dokumentasi

Minggu ke-4, 10/05 - 10/11:

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

Minggu ke-5, 12/10 - 18/10:

Menyiapkan 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 ada untuk metadata OpenGraph menjadi ekstensi Sphinx yang dapat di-deploy
Merevisi pedoman gaya berdasarkan masukan dari sesi Tanya Jawab dengan kontributor Bokeh

Minggu ke-6, 19/10 - 25/10:

Mulai pengujian alat untuk kontrol 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 berdasarkan masukan dari sesi Tanya Jawab kedua

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

Deploy ekstensi Sphinx dan publikasikan dokumentasi naratif yang ditingkatkan serta halaman landing dokumentasi

Minggu ke-9, 09/11 - 15/11:

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

Minggu 10, 16/11 - 22/11:

Menyelesaikan tugas yang tersisa

Minggu ke-11, 23/11 - 29/11:

Mulai menulis laporan project
Mulai menulis evaluasi project

Fase penyelesaian project

Minggu ke-12, 30/11 - 12/05:

Menyelesaikan dan mengirimkan laporan project

Minggu ke-13, 03/12 - 10/12:

Menyelesaikan dan mengirimkan evaluasi project

Setelah berakhirnya Musim Dokumen Google:

Saya berharap dapat tetap terlibat dalam pengembangan Bokeh dan terus mengerjakan dokumentasi Bokeh.
Saya berencana melanjutkan pengembangan ekstensi Sphinx untuk metadata OpenGraph/Data Terstruktur.
Saya berharap dapat menggunakan latar belakang saya dalam 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 setelan jurnalistik.

6. Tentang diri saya

Saya awalnya adalah seorang jurnalis, dengan latar belakang berita TV, online, dan radio. Bekerja sebagai editor 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 digital dan otomatisasi. Saya menulis banyak manual yang membahas alat dan alur kerja digital, serta panduan gaya dan strategi komunikasi untuk brand berita digital. Saya juga melatih anggota tim dalam menggunakan alat tersebut.

Saya selalu tertarik dengan persimpangan antara komunikasi dan teknologi. Dunia baru terbuka bagi saya saat saya belajar membuat kode di Python: Saya dapat melakukan analisis dan visualisasi data untuk jurnalisme data, misalnya. Belajar coding juga memungkinkan saya untuk secara aktif bekerja sama dengan engineer software dalam mengembangkan alat digital untuk alur kerja ruang redaksi.

Sayangnya, manual dan dokumen yang saya tulis di pekerjaan sebelumnya bersifat non-publik. Oleh karena itu, saya sekarang berfokus untuk lebih terlibat dengan project open source (lihat contoh di bawah). Saya telah mendasarkan pekerjaan saya dalam 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 narasi serta docstring dan petunjuk jenis, menggunakan alat seperti Sphinx, Mypy, dan Sphinx autodoc.

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

7. Contoh dokumentasi open source terbaru

PyZillow: PyZillow adalah wrapper Python untuk API situs real estate Zillow.com. Selain menyediakan beberapa kode dan bertindak sebagai salah satu pengelola kode, saya menulis dokumentasi lengkap. Saya menggunakan Sphinx untuk dokumentasi narasi, 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 situs presseportal.de. Situs presseportal.de adalah salah satu distributor rilis pers dan pengumuman hubungan investor terbesar di Jerman. Misalnya, hampir semua departemen kepolisian dan pemadam kebakaran menggunakan layanan ini untuk mendistribusikan rilis pers mereka. Setelah menggunakan API selama bertahun-tahun sebagai jurnalis, saya memutuskan untuk mengembangkan antarmuka Python guna mengakses resource data yang luas di situs tersebut sebagai objek Python. Saya menulis kode dan seluruh dokumentasi berbasis Sphinx.