Proyek Uji Coba Bersama

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

Ringkasan project

Organisasi open source:
Performance Co-Pilot
{i>Technical writer <i}(Penulis teknis):
arzoo14
Nama project:
Mengonversi konten area project buku ke format readthedocs dan reStructuredText beserta sasaran perpanjangan peningkatan diagram.
Durasi project:
Durasi standar (3 bulan)

Project description

ABSTRAK:

Situs komunitas memainkan peran penting dalam organisasi open-source karena menyebarkan gagasan tentang penawaran yang diberikan komunitas, kontribusi mereka yang berharga, keterampilan mereka, dokumentasi mereka, tutorial mereka, dll. Jadi, project saya akan bertujuan untuk meningkatkan kegunaan dan kemudahan bagi semua kontributor open source dengan mentransfer dan memperbarui konten area proyek buku, yaitu, konten docbook, dokumentasi API yang dihosting, dan format piobench yang dihosting oleh komunitas di situs tersebut. Project ini juga akan menguntungkan kontributor komunitas dengan memungkinkan mereka mengubah dan memperluas konten ini dengan lebih mudah. Selain itu, sebagai sasaran tambahan, diagram dalam dokumentasi akan ditingkatkan kualitasnya agar terlihat lebih profesional.

PROPOSAL:

  1. RINGKASAN: Dokumentasi Performa Uji Coba Bersama saat ini tersedia dalam beberapa format yang berbeda. Ini termasuk buku PCP dalam format docbook, REST API dalam format manpage, dan panduan pbench dalam format markdown. Jadi, grup pengelola organisasi saat ini mengidentifikasi bahwa mereka membutuhkan solusi yang bebas pemeliharaan, dan hal itu memungkinkan komunitas developer untuk sepenuhnya fokus pada pemeliharaan kontennya dengan cara yang sederhana dan mudah. Jadi, sesuai dengan kebutuhan organisasi saat ini, saya akan menerapkan sasaran berikut selama Google Season of Docs ini:

    1. Mengonversi konten docbook ke format reStructuredText dan menghostingnya di situs readthedocs.
    2. Mengonversi dokumentasi REST API dari halaman manual menjadi format yang cocok untuk developer, yaitu format reStructuredText dan menghostingnya di situs readthedocs.
    3. Mengonversi konten MarkDown pbench ke format reStructuredText dan menghostingnya di situs readthedocs.
    4. Sasaran tambahannya adalah meningkatkan kualitas diagram yang ada dalam dokumentasi.

  2. PENERAPAN: Saat ini, dokumentasi Uji Coba Bersama Performa tidak ada dalam format tertentu. Setiap kali konten dokumentasi perlu diubah, konten harus diubah oleh sekelompok pengguna yang terbatas. Tidak mudah bagi anggota komunitas aktif untuk mengubah dan memperluas konten dokumentasi.

Saya akan membiarkan organisasi mengatasi batasan ini selama GSoD ini dengan bantuan format reStructuredText, Read the Docs (RTD), dan Sphinx.

Baca Dokumen (RTD) menyederhanakan dokumentasi software dengan mengotomatiskan pembuatan, pembuatan versi, dan hosting dokumen untuk kami. Ini adalah platform hosting untuk dokumentasi yang dibuat Sphinx. Sphinx menggunakan kemampuan Sphinx dan menambahkan kontrol versi, penelusuran teks lengkap, dan fitur berguna lainnya. Alat ini mengambil file kode dan dokumen dari Git, Mercurial, atau Subversion, lalu mem-build dan menghosting dokumentasi kita. Kita akan menggunakan GitHub dalam project karena merupakan sistem yang paling umum digunakan untuk mengakses kode.

Untuk memulai, kita akan membuat {i>Read the Docs account<i}, dan menautkan akun GitHub. Kemudian kita akan memilih repositori GitHub yang ingin dibuatkan dokumentasinya, dan pada saat itu terjadi keajaiban.

Read the Docs akan: - Meng-clone repositori kami. - Membuat dokumentasi versi HTML, PDF, dan ePub dari cabang master kami. - Mengindeks dokumentasi kami untuk mengizinkan penelusuran teks lengkap. - Membuat objek Versi dari setiap tag dan cabang di repositori, sehingga kita dapat menghostingnya secara opsional. - Mengaktifkan webhook di repositori, sehingga saat kita mendorong kode ke cabang mana pun, dokumentasi kita akan di-build ulang.

Sphinx adalah generator dokumentasi resmi yang memiliki banyak fitur hebat untuk menulis dokumentasi teknis, termasuk: - Membuat halaman web, PDF yang dapat dicetak, dokumen untuk e-reader (ePub), dan lainnya, semuanya dari sumber yang sama. - Kita dapat menggunakan reStructuredText untuk menulis dokumentasi. - Sistem dokumentasi dan kode referensi silang yang luas. - Contoh kode yang ditandai sintaksis. - Ekosistem ekstensi pihak pertama dan pihak ketiga yang beragam.

Saya akan mulai dengan mengonversi dua buku PCP yang ada dalam format docbook ke format rst, mengikuti konversi dokumentasi REST API dari format man page ke format rst, lalu konversi konten markdown pbench ke format rst dan pada akhirnya, menghosting semua ini di situs readthedocs. Sasaran perpanjangannya adalah meningkatkan diagram dalam dokumentasi.

2.1. Konversi ke format reStructuredText: Langkah pertama adalah mengonversi konten dokumentasi ke dalam format reStructuredText. Setiap bab akan memiliki file rst terpisah, yang hanya akan berisi konten bab tersebut. Misalnya, buku Panduan Pengguna dan Administrator Performance Co-Pilot mencakup delapan bab. Artinya, akan ada delapan file rst berbeda yang sesuai dengan delapan bab tersebut. Nama file pertama akan sama dengan nama bab untuk menghindari kebingungan di masa mendatang. Daftar gambar, tabel, dan contoh akan ada di tiga file pertama yang berbeda. Konten rst akan diberi hyperlink secara menyeluruh dengan cara yang sama seperti saat ini. Hal yang sama akan digunakan untuk dokumentasi REST API dan konten pbench. Semua hal yang diperlukan, seperti tebal, miring, garis bawah, poin butir, tabel, ukuran font, gaya kode, ukuran gambar, perataan, dll., akan ditangani saat mengonversi konten ke format rst.

2.2. Integrasi rst dengan Sphinx:

ReadtheDocs menggunakan Sphinx dan reStructuredText (rst) sebagai default. Karena Sphinx sudah diinstal sebelumnya di sistem saya, saya akan memulai dengan membuat direktori di dalam project (bernama Dokumentasi Performance Co-Pilot) untuk menyimpan dokumen: $ cd /path/to/project $ mkdir docs

Setelah itu, jalankan sphinx-quickstart di sana: $ cd docs $ sphinx-quickstart

Mulai cepat ini akan memandu pembuatan konfigurasi yang diperlukan; dalam sebagian besar kasus, kita hanya dapat menerima setelan default (tetapi jika diperlukan, kita dapat membuat perubahan penting dalam file konfigurasi). Setelah selesai, kita akan memiliki index.rst, conf.py, dan beberapa file lainnya. Di index.rst, saya akan menambahkan semua detail yang diperlukan tentang Performance Co-Pilot dan akan membuat judul untuk buku, dokumentasi REST API, dan panduan pbench. Saat pengguna mengklik salah satu judul, semua materi dokumentasi di bawah judul tersebut akan terbuka.

CATATAN: Desain halaman indeks akan sesuai dengan izin mentor dan anggota komunitas serta akan diubah sesuai kebutuhan dan persyaratan.

index.rst akan di-build ke dalam index.html di direktori output dokumentasi kita (biasanya _build/html/index.html). Setelah memiliki dokumentasi Sphinx di repositori publik, kita dapat mulai menggunakan Read the Docs dengan mengimpor dokumen.

Saat kita menambahkan file .rst dalam dokumentasi, tiga file lain akan dibuat sesuai dengan file tersebut, satu di folder doctrees dengan ekstensi .doctree, yang kedua di folder Html dengan ekstensi .html, dan yang ketiga di folder html/_sources dengan ekstensi .rst.txt.

  1. MENGHOSTING DOKUMENTASI: Hosting dokumentasi di internet terdiri dari dua langkah: 1. Mengimpor dokumentasi: Sebagai langkah pertama, saya akan menghubungkan akun Read The Docs dengan GitHub dan mengimpor project dokumentasi untuk di-build. 2. Mem-build dokumentasi: Dalam beberapa detik setelah menyelesaikan proses impor, kode akan otomatis diambil dari repositori publik kami, dan dokumentasi akan di-build.

  2. WEBHOOKS: Metode utama yang digunakan Baca Dokumen untuk mendeteksi perubahan pada dokumentasi dan versi adalah melalui penggunaan webhook. Webhook dikonfigurasi dengan penyedia repositori kami, seperti GitHub, dan dengan setiap commit, penggabungan, atau perubahan lain pada repositori kami, Read the Docs akan diberi tahu. Saat menerima notifikasi webhook, kami akan menentukan apakah perubahan tersebut terkait dengan versi aktif untuk project kami, dan jika ya, build akan dipicu untuk versi tersebut.

Dengan cara ini, siapa pun (admin, mentor, kontributor komunitas) dapat mengubah, memperluas, atau mengelola dokumentasi komunitas, dan tidak ada sekumpulan pengguna tertentu yang dibatasi untuk menangani apa yang harus ditambahkan ke dokumentasi atau apa yang harus dihapus dari dokumentasi.

  1. TEMA: Tema, tata letak, desain, dan fungsi HTML lainnya seperti penelusuran akan sesuai dengan kebutuhan dan pedoman komunitas. Dalam periode ikatan komunitas, saya akan membahas semua hal ini dengan anggota komunitas.
  1. STRETCH GOAL: Sebagai tujuan tambahan, saya akan memperbaiki diagram yang ada dalam dokumentasi. Saat ini, diagram sebagian besar berupa gambar hitam-putih sederhana. Saya akan memperkenalkan lebih banyak warna, bayangan, penskalaan, konsistensi, dan tampilan yang umumnya lebih rapi / lebih profesional pada gambar.

Untuk mencapai tujuan ini, saya akan menggunakan draw.io (atau alat lainnya dengan izin dari mentor).

Sebagai Proof of Concept, saya telah meningkatkan kualitas salah satu diagram yang ada dalam dokumentasi dengan bantuan draw.io. Temukan di sini: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

BUKTI KONSEP

Saya telah mengonversi sebagian kecil buku PCP (format docbook) ke format rst dan menghostingnya di situs readthedocs. Temukan di sini.

Situs - https://pcp-books.readthedocs.io/en/latest/ Kode - https://github.com/arzoo14/PCP_Books_Demo

Saya juga telah mengonfigurasi webhook di repositori kode dengan bantuannya, perubahan yang dilakukan dalam repositori kode akan tercermin di situs.

LINTAS WAKTU DAN HASIL KERJA

PERIODE PENGEMBANGAN KOMUNITAS [17 Agustus - 13 September 2020 ]

Saya akan menghabiskan waktu ini untuk membiasakan diri dengan komunitas, membaca dokumentasi, dan mendiskusikan banyak hal dengan mentor untuk memastikan tidak ada keputusan buruk yang dibuat di awal proses. Saya akan membahas tema, tata letak, desain, fungsi lain seperti penelusuran, menu navigasi, dll. dengan mentor dan anggota komunitas selama periode ini. Keputusan atas nama proyek dan apakah akan ada situs web untuk menghosting ketiga topik tersebut atau tiga situs web berbeda yang sesuai dengan ketiga topik tersebut akan dibahas selama periode ikatan komunitas.

PERIODE PEMBUATAN DOC [14 September - 30 November 2020 ]

***Dari 14 September 2020 hingga 20 September 2020 [MINGGU 1] Konversi konten docbook menjadi format rst untuk empat bab pertama buku Panduan Pengguna dan Administrator.

***Dari 21 September 2020 hingga 27 September 2020 [MINGGU 2] Konversi konten docbook menjadi format rst untuk empat bab berikutnya dari buku Panduan Pengguna dan Administrator.

***Dari 28 September 2020 hingga 4 Oktober 2020 [MINGGU 3] Konversi konten docbook ke dalam format pertama untuk keempat bab dalam buku Panduan Programmer.

***Dari 5 Oktober 2020 hingga 11 Oktober 2020 [MINGGU 4] - Hosting kedua buku PCP di situs readthedocs. - Konversi dokumentasi REST API dari man page ke format rst. Halaman landing utama akan dibahas selama periode ini. - Blogging (proyek GSoD saya) selama tiga minggu terakhir dan minggu ini.

***Dari 12 Oktober 2020 hingga 18 Oktober 2020 [MINGGU 5] Konversi indeks Deret Waktu yang Dapat Diskalakan menjadi format rst. Indeks Deret Waktu yang Skalabel mencakup hal-hal berikut: GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/load

***Dari 19 Oktober 2020 hingga 25 Oktober 2020 [MINGGU 6] Konversi indeks Layanan Host PMAPI menjadi format rst. Indeks Layanan Host PMAPI mencakup hal berikut: GET /pmapi/context, GET /pmapi/metric, GET /pmapi/fetch , GET /pmapi/children GET /pmapi/indom, GET /pmapi/profile , GET /pmapi/store , GET /pmapi/derive GET /pmapi/metrics

***Dari 26 Oktober 2020 hingga 1 November 2020 [MINGGU 7] - Jika ada yang tersisa dalam minggu-minggu terakhir, hal itu akan dibahas terlebih dahulu. - Hosting dokumentasi REST API di situs readthedocs. - Membuat blog (tentang project GSoD saya) selama dua minggu terakhir dan minggu ini.

***Dari 2 November 2020 hingga 8 November 2020 [MINGGU 8] Konversi konten markdown menjadi format rst untuk panduan pbench.

***Dari 9 November 2020 hingga 15 November 2020 [MINGGU 9] - Melanjutkan konversi konten markdown menjadi format rst untuk panduan pbench. - Hosting panduan pbench di situs readthedocs. - Membuat blog (tentang project GSoD saya) selama seminggu terakhir dan minggu ini.

***Dari 16 November 2020 hingga 22 November 2020 [MINGGU 10] - Penerapan fungsi penelusuran di halaman indeks untuk menelusuri konten apa pun dari namanya di situs. - Mulainya stretch goal.

***Dari 23 November 2020 hingga 30 November 2020 [MINGGU 11] - Peningkatan semua diagram yang ada dalam dokumentasi. - Blogging akhir (dari project GSoD saya) untuk minggu terakhir dan minggu ini. - Memeriksa apakah codebase sesuai dengan standar coding atau tidak. Jika tidak, ubah ke standar.

PERIODE AKHIRIZASI PROJECT [ 30 November - 5 Desember 2020 ]

  • Periode nonaktif pensil. Mengerjakan tugas akhir dan memastikan semuanya baik-baik saja.
  • Pengiriman laporan project, yang juga dikenal sebagai produk kerja akhir.
  • Pengiriman evaluasi keberhasilan project dan pengalaman bekerja dengan mentor.