Project GenPipes

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

Ringkasan project

Organisasi open source:
GenPipes
Penulis teknis:
shaloo
Nama project:
Menyiapkan dokumen GenPipes di 'Read The Docs'
Durasi project:
Durasi standar (3 bulan)

Project description

Saya mengusulkan rencana 3 langkah untuk mencapai tujuan menyiapkan dokumentasi GenPipes di 'Read The Docs'.

Langkah 1: PoC

  • Meninjau dokumentasi GenPipes yang ada sebagai pengguna / peneliti baru

    • Mengidentifikasi informasi yang hilang, ketidakakuratan
    • Menyarankan topik dokumen baru (jika diperlukan)
    • Draf peta arsitektur informasi untuk menjangkau target audiens, dengan fokus pada pengguna baru.

    (Catatan: Selama langkah ini, kami mungkin juga memerlukan input 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 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 sampler yang saya buat untuk proposal ini)

  • Berdasarkan peninjauan dan analisis pada langkah sebelumnya, buat kerangka dasar struktur / indeks Dokumentasi GenPipes yang diusulkan dan tampilkan di situs RTD

    • Hal ini mencakup pembuatan repo GitHub (misalnya dengan alat Sphinx) dan file dokumentasi dasar
    • Hal ini juga melibatkan pembuatan daftar isi baru yang mempertimbangkan berbagai bagian / alur informasi kepada pengguna baru dan pengguna berpengalaman.

  • Meninjau / mendapatkan persetujuan pada TOC kerangka dasar

    Selama fase evaluasi GSoD GenPipes, saya mencoba membuat nilai untuk GenPipes melalui sampel ini yang dihosting di RTD. Perhatikan bahwa ini hanya untuk tujuan demo, link yang dilindungi, dan belum dicantumkan secara publik di RTD. Terlepas dari apakah saya terpilih atau tidak, demo ini dapat digunakan untuk memulai upaya RTD GenPipes. Saya telah memeriksa sumber di repo GitHub c3g/GenPipes. Mentor, Rola dan Hector menyukainya selama diskusi 'berbagi layar' Skype sebelumnya, jadi saya pikir Dewa GSoD mungkin juga ingin melihatnya. Untuk saat ini, saya berencana untuk memperbaruinya jika waktu memungkinkan hingga 30 Juli.

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

Langkah 2: Pembuatan docset GenPipes Doc v0.9

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

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

    • Impor dokumen awal yang ditetapkan ke ReadTheDocs sebagai Proof of Concept – hosting di sana sebagai repositori yang dilindungi. Berikan catatan di awal yang menyarankan pengguna baru untuk membuka dokumentasi asli GenPipes hingga peninjauan/peralihan formal disetujui.

  • Review/course-correct/update

Langkah 3: Meningkatkan kualitas, Meninjau, dan Memublikasikan draf pertama di RTD

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

  • Tambahkan demarkasi yang jelas di TOC untuk menargetkan pengguna baru, pengguna GenPipes berpengalaman, developer GenPipes, dll.

  • Menyarankan, mendiskusikan proses kerja dengan otomatisasi bagian melalui RTD (build sphinx) tentang cara set dokumen GenPipes dapat dikelola, diedit oleh pengguna, dan apakah C3G akan mengizinkannya untuk kontributor dokumen eksternal. Ini mungkin memerlukan beberapa pembuatan panduan untuk pembaruan dokumen yang mirip dengan panduan pengkodean. Mungkin memerlukan lebih banyak sub-langkah. Misalnya, otomatiskan pemeriksaan ejaan sebelum persetujuan PR di dokumen GenPipes.

Laporkan

Terakhir, Buat laporan untuk GSoD berdasarkan pengalaman, log, masukan dari mentor.

Pikiran lainnya

Di masa mendatang (lebih dari 3 bulan), jika berlaku, saya dapat membantu mempertahankannya untuk GenPipes dalam jangka waktu yang lebih lama. Atau, latih orang lain, jika diperlukan, untuk melakukan hal yang sama. Kita dapat mengetahuinya berdasarkan hasil 3 bulan pertama ini.

Selain itu, saya menyarankan ide proposal proyek tambahan - pembuatan ringkasan halaman GenPipes 3 yang memudahkan orientasi. Saat ini, pengguna baru harus melakukan banyak hal sebelum dapat memulai GenPipes karena dokumentasinya bagus, tetapi tersebar dan tidak kondusif bagi pengguna baru. Tidak yakin apakah ini dapat dilakukan dalam waktu 3 bulan, tetapi saya ingin mencobanya.

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