Project GenPipes

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

Ringkasan proyek

Organisasi open source:
GenPipes
Penulis teknis:
shaloo
Nama proyek:
Menyiapkan dokumen GenPipes di 'Baca Dokumen'
Durasi proyek:
Durasi standar (3 bulan)

Project description

Saya mengusulkan rencana 3 langkah untuk mencapai tujuan penyiapan dokumentasi GenPipes di 'Baca Dokumen'.

Langkah 1: PoC

  • Tinjau dokumentasi GenPipes yang ada sebagai pengguna / peneliti baru

    • Mengidentifikasi informasi yang hilang, ketidakakuratan
    • Sarankan topik dokumen baru (jika perlu)
    • Menyusun konsep peta arsitektur informasi untuk menangani audiens target, dengan fokus pada pengguna baru.

    (Catatan: Selama langkah ini, kita mungkin juga memerlukan input dari mentor GenPipes mengenai pengaturan repositori GitHub baru tempat dokumen genpipes untuk RTD dapat dihosting. Repositori GitHub ini dapat digunakan untuk mengimpor semua dokumen dalam pipeline build RTD. Hal ini mungkin memerlukan insight tentang aturan repo GenPipes dan panduan pengelolaan sumber dokumen jika ada yang perlu dipatuhi. Jika tidak, yang standar dapat digunakan, afaik. Selain itu, untuk PoC, saya dapat mendemonstrasikan contoh penyiapan repo RTD menggunakan akun GitHub saya - misalnya, https://gpdocs.readthedocs.io/en/latest/ - ini adalah contoh yang saya buat untuk proposal ini)

  • Berdasarkan tinjauan dan analisis pada langkah sebelumnya, buat kerangka barebone dari struktur / indeks Dokumentasi GenPipes yang diusulkan dan letakkan di situs RTD

    • Hal ini melibatkan pembuatan repo GitHub (misalnya dengan alat Sphinx) dan file dokumentasi dasar
    • Hal ini juga melibatkan pembuatan TOC baru yang mempertimbangkan pengguna baru dan pengguna berpengalaman untuk berbagai bagian / aliran informasi.

  • Tinjau / dapatkan persetujuan atas TOC kerangka barebone

    Selama fase evaluasi GSoD GenPipes, saya mencoba membuat nilai untuk GenPipes melalui contoh ini yang dihosting di RTD. Perhatikan bahwa ini hanya untuk tujuan demo, link yang dilindungi, yang belum dicantumkan secara publik di RTD. Terlepas dari apakah saya masuk dalam daftar pendek atau tidak, demo ini dapat digunakan untuk mempercepat upaya GenPipes RTD. Saya sudah memeriksa sumbernya di repo GitHub c3g/GenPipes. Para mentor, Rola dan Hector menyukainya selama diskusi "berbagi layar" di Skype sebelumnya, jadi saya pikir Dewa GSoD mungkin juga ingin melihatnya. Kerangka barebone-nya untuk saat ini, tapi aku berencana untuk memperbaruinya saat waktu memungkinkan hingga 30 Juli.

https://genpipes.readthedocs.io/en/latest/

Langkah 2: Pembuatan dokumen GenPipes Doc v0.9

  • Identifikasi dokumen GenPipes saat ini atau yang sudah ada yang dapat diimpor, ditautkan, atau dikonversi ke dokumentasi berbasis Sphinx/rst untuk dihosting di RTD dengan mempertimbangkan linimasa GSoD

  • Konversikan dokumen yang diidentifikasi ke format rst, jika perlu, buat dokumen baru jika ada, gunakan kembali apa pun yang memungkinkan / relevan.

    • Impor dokumen awal yang disetel ke ReadTheDocs sebagai Bukti Konsep – hosting dokumen tersebut sebagai repo yang dilindungi. Tulis catatan di awal yang menyarankan pengguna baru untuk membuka dokumentasi asli GenPipes hingga peninjauan/beralih formal diperbolehkan.

  • Tinjau/course-correct/update

Langkah 3: Saring, Tinjau, dan Publikasikan draf pertama di RTD

  • Isi detail struktur dokumen baru GenPipes yang diajukan ke dalam TOC GenPipes – Tambahkan dokumen tambahan selain beberapa dokumen pertama (GenPipes Readme), Concepts, Tutorial, dll.

  • Tambahkan demarkasi yang jelas dalam TOC untuk menangani pengguna baru, pengguna GenPipes yang berpengalaman, developer GenPipes, dll.

  • Sarankan, diskusikan proses kerja dengan otomatisasi bagian melalui RTD (build sphinx) tentang bagaimana dokumen GenPipes dapat dikelola, diedit oleh pengguna, dan apakah C3G akan mengizinkannya untuk kontributor dokumen eksternal. Hal ini mungkin memerlukan beberapa pembuatan pedoman untuk pembaruan dokumen yang mirip dengan pedoman pengkodean. Mungkin memerlukan lebih banyak sub-langkah. Misalnya, mengotomatiskan pemeriksaan ejaan sebelum persetujuan PR di dokumen GenPipes.

Laporkan

Terakhir, Buat laporan untuk GSoD berdasarkan pengalaman, catatan, umpan balik dari mentor.

Hal lainnya

Di masa mendatang (lebih dari 3 bulan), jika berlaku, saya dapat membantu mempertahankan hal ini untuk GenPipes dalam jangka waktu yang lebih panjang. Atau, melatih orang lain, jika perlu, untuk hal yang sama. Kami dapat mengetahuinya berdasarkan hasil selama 3 bulan pertama.

Selain itu, saya sarankan ide proposal proyek tambahan - pembuatan rangkuman halaman GenPipes 3 yang membantu orientasi dengan mudah. Saat ini, pengguna baru harus melakukan banyak rintangan sebelum dapat memulai GenPipes karena dokumentasinya bagus tetapi tersebar dan tidak kondusif bagi pengguna baru. Saya tidak yakin apakah ini bisa dilakukan dalam waktu 3 bulan, tetapi saya ingin mencoba dan mencobanya.

Proposal yang sama dan bagaimana asalnya (histori) juga dapat dilihat di https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing