Project GenPipes

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

Ringkasan proyek

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

Project description

Saya mengusulkan rencana 3 langkah untuk mencapai tujuan penyiapan dokumentasi GenPipes tentang 'Read The Docs'.

Langkah 1: PoC

  • Tinjau dokumentasi GenPipes yang ada sebagai pengguna / peneliti baru

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

    (Catatan: Selama langkah ini, kami mungkin juga memerlukan masukan dari mentor GenPipes terkait penyiapan repositori GitHub baru tempat dokumen genpipes untuk RTD dapat dihosting. Repo GitHub ini dapat digunakan untuk mengimpor semua dokumen di pipeline build RTD. Hal ini mungkin memerlukan insight tentang aturan repo GenPipes dan pedoman pengelolaan sumber dokumen jika ada yang perlu dipatuhi. Jika tidak, yang standar dapat digunakan, afaik. Selain itu untuk PoC, saya dapat mendemonstrasikan contoh pengaturan 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 tempatkan 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 pada TOC kerangka barebones

    Selama fase evaluasi GSoD GenPipes, saya mencoba menciptakan nilai untuk GenPipes melalui contoh ini yang dihosting di RTD. Perhatikan bahwa ini hanya untuk tujuan demo, link terlindungi, belum dicantumkan secara publik di RTD. Terlepas dari apakah saya terpilih atau tidak, demo ini dapat digunakan untuk memulai upaya GenPipes RTD. Saya sudah memeriksa sumbernya di repositori GitHub c3g/GenPipes. Mentor, Rola dan Hector menyukainya selama diskusi 'berbagi layar' Skype sebelumnya, jadi saya pikir GSoD Gods mungkin ingin melihatnya juga. Kerangkanya tanpa tulang 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

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

  • Konversi dokumen yang diidentifikasi ke format pertama, jika perlu, buat dokumen baru jika memungkinkan, gunakan kembali dokumen apa pun yang memungkinkan / relevan.

    • Impor kumpulan dokumen awal ini ke ReadTheDocs sebagai Proof of Concept – simpan dokumen tersebut sebagai repo yang dilindungi. Tulis catatan di awal yang menyarankan pengguna baru untuk membuka dokumentasi asli GenPipes hingga peninjauan/pengalihan resmi diberikan untuk melanjutkan.

  • Tinjau/kursus-benar/perbarui

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

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

  • Menambahkan demarkasi yang jelas dalam TOC untuk menangani pengguna baru, pengguna GenPipes 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 panduan untuk pembaruan dokumen yang mirip dengan pedoman coding. Mungkin memerlukan lebih banyak sub-langkah. Misalnya, otomatiskan periksa ejaan sebelum persetujuan PR di dokumen GenPipes.

Laporkan

Terakhir, buat laporan untuk GSoD berdasarkan pengalaman, catatan, masukan dari mentor.

Pikiran lainnya

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

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

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