Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.
Ringkasan proyek
- Organisasi open source:
- Gateway gRPC
- Penulis teknis:
- iamrajiv
- Nama proyek:
- Memfaktorkan Ulang Situs Dokumen yang Ada di gRPC-Gateway
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
ABSTRAK:
Situs dokumen pengguna dirancang untuk membantu pengguna akhir menggunakan suatu produk atau layanan. Situs dokumen pengguna yang baik sangat penting karena menyediakan jalur bagi pengguna untuk mempelajari cara menggunakan perangkat lunak, fiturnya, kiat, trik, dan juga menyelesaikan masalah umum yang dihadapi saat menggunakan perangkat lunak tersebut. Ini juga mengurangi biaya dukungan dan merupakan bagian dari identitas perusahaan produk. Situs dokumen pengguna yang baik adalah tanda dari kesehatan produk, tim pengembang. Tanpa situs dokumen pengguna yang baik, pengguna mungkin tidak tahu bagaimana melakukan hal-hal di atas secara efektif dan efisien. Situs dokumen pengguna dapat memainkan peran penting dalam memastikan keberhasilan sebuah produk karena komunikasi yang baik adalah dan akan selalu menjadi jantung bisnis atau produk apa pun dan dokumentasi yang bagus hanya mengambil komunikasi itu dan menempatkannya dalam kerangka kerja yang mudah dikelola yang dapat diakses setiap orang untuk sukses.
Pada saat penulisan ini, repositori gRPC-Gateway telah diambil oleh sekitar 1.200 kali dan 184 orang telah berkontribusi pada repositori ini. Hal ini menunjukkan bahwa banyak orang di seluruh dunia menggunakan gRPC-Gateway dan mungkin ingin membaca dokumentasi penggunanya untuk panduan tentang cara menggunakan gRPC-Gateway. Namun, dokumentasi pengguna dan situs dokumen gRPC-Gateway saat ini sudah usang dan belum lengkap, dan komunitas gRPC-Gateway ingin menggunakan project ini untuk memfaktorkan ulang situs dokumen yang ada, meningkatkan situs dokumennya untuk memungkinkan pengguna akhir mendapatkan pengalaman yang lancar saat menggunakan gRPC-Gateway.
NEGARA BAGIAN SAAT INI:
Saat ini, situs dokumen gRPC-Gateway memiliki dua masalah utama:-
• Masalah pertama adalah situs dokumen yang buruk dan usang yaitu gaya dan struktur situs dan tema yang digunakan sudah usang, tidak lengkap, sulit dinavigasi atau menemukan informasi, tidak mencakup banyak fitur situs dokumen yang baik. Memfaktorkan ulang Situs Dokumen yang Ada dari gRPC-Gateway akan mencakup penataan gaya situs, menambahkan fitur seperti penelusuran dokumen dll., meningkatkan UI situs, mengatur tutorial dan contoh di sidebar yang tepat, serta memperbarui diagram alur dan gambar yang ada dengan merancang yang baru, dll. Ini akan menjadi tujuan utama saya dan pekerjaan saya akan lebih didasarkan pada penataan gaya dan restrukturisasi situs Dokumen yang ada.
• Masalah kedua, ada kebutuhan untuk memfaktorkan ulang dokumentasi, tutorial, dan contoh dll gRPC-Gateway yang ada, yang bisa dilakukan dengan menghapus kesalahan tipografi dan tata bahasa pada file, membuat penyelarasan yang tepat terhadap cuplikan Go dan memfaktorkan ulang cuplikan Go sesuai dengan format Gofmt. Selain itu, jika perlu, kita dapat menambahkan lebih banyak dokumentasi, tutorial, dan contoh jika perlu atau kita dapat menggunakan kembali file yang ada setelah memfaktorkan ulang file tersebut. Ini adalah sasaran sekunder saya dan akan melakukan ini setelah saya menyelesaikan tujuan utama saya, yaitu menata gaya dan menyusun ulang situs Dokumen yang ada.
MENGAPA DOKUMEN YANG DISARANKAN SAYA MENJADI PERBAIKAN DI ATAS YANG SAAT INI?
Situs dokumen pengguna yang diusulkan akan disusun untuk meningkatkan dan memastikan efisiensi, konsistensi, dan ketenangan pikiran bagi pengguna akhir. Ini akan memberikan tampilan dan UI yang lebih baik dengan bagian dan fitur yang dirancang dengan baik berisi panduan tertulis serta diagram alir dan gambar terkait.
Dokumentasi gRPC-Gateway memberikan deskripsi metode dan contoh yang baik. Tapi masih menggunakan tema Jekyll lama dan sekarang kami memiliki tema Jekyll SSG (Static Site Generator) yang lebih baik. Selain itu, ada kebutuhan untuk menyusun ulang halaman dan membuatnya lebih berguna bagi pengguna dengan menambahkan contoh dan tutorial baru serta memperbarui dan menulis ulang konten sebelumnya.
STRUKTUR DAN TAHAPAN TARGET DAN IDE YANG DISARANKAN:
SASARAN UTAMA PROJECT INI:-
Sasaran dan ide di atas dapat diterapkan dengan cara berikut:-
Menggeser tema Jekyll Saat Ini ke tema yang lebih baik dan mendalam. Alasan untuk menggunakan tema Jekyll lagi adalah karena pengelola akan lebih mudah berkontribusi dan memahami alur kerja proyek karena mereka sudah mengetahui kerangka kerja dan tema Jekyll yang ada yang mirip dengan tema Jekyll baru.
Setelah melalui berbagai tema Jekyll di internet, saya mendapati bahwa suite tema https://idlokalbewriting.com/documentation-theme-jekyll/ ini paling cocok untuk situs dokumen gRPC-Gateway karena fitur berikut:
• Markdown:- Agar penulis teknis tidak perlu mengkhawatirkan penginstalan. Mereka hanya dapat menulis di {i>file<i} .md. Siapa pun dapat mengklik tombol edit yang ditampilkan di situs (fitur baru) dan berkontribusi (edit/menyarankan perubahan untuk halaman di GitHub) agar lebih baik. Cara ini akan melibatkan pengguna untuk menambahkan konten baru atau mengedit konten untuk meningkatkannya.
• Penelusuran Dokumentasi:- Pengguna harus memiliki kotak penelusuran sehingga dapat dengan mudah dan cepat menemukan konten yang relevan.
• Bagian Komentar:- Pengguna dapat memiliki opsi untuk mengomentari dan berbagi pandangan mereka pada postingan dan tutorial. Mereka dapat membaca pandangan orang lain tentang dokumentasi proyek.
• Catatan dan Blog Rilis Baru:- Situs harus diperbarui dengan postingan blog baru dan berita tentang pengembangan dan roadmap saat ini. Jenis {i>blogging<i} harus ada di halaman muka.
• Pengembangan Cepat:- Sebagian besar framework SSG (Static Site Generator) berjalan di server dan perubahan file langsung tercermin di UI. Selain itu, proses deploy dan build seharusnya mudah. Di masa mendatang, jika ingin mengubah framework, kami menggunakan. Maka seharusnya mudah. Sebagian besar kerangka kerja mendukung penulisan Markdown sehingga cukup dengan memindahkan {i>file<i} .md dan beberapa perubahan sudah cukup.
Di sini saya membagi halaman situs yang ada menjadi beberapa bagian dan halaman situs baru :
• Halaman Landing:-
Halaman landing harus menunjukkan fitur utama gRPC-Gateway.
- Mulai menggunakan gRPC-Gateway (dialihkan ke panduan pengguna)
- Petunjuk Penginstalan sederhana (perintah singkat)
- Alasan menggunakan gRPC-Gateway
- Project menggunakan gRPC-Gateway
Jadi, ide dasarnya adalah daripada menulis deskripsi panjang, tampilkan poin utama di halaman landing dan berikan link untuk melihat detailnya.
• Halaman Panduan Pengguna Gateway gRPC:-
- Panduan penginstalan.
- Mulai cepat dengan gRPC-Gateway.
• Halaman Panduan Developer Gateway gRPC:-
Panduan Pengembangan, Panduan kontribusi, Penyiapan Git, Kode Etik, Penyiapan dokumentasi, Alur kerja pengembangan, dll. mengarah ke halaman serupa di dalamnya. Jadi, diperlukan pemfaktoran ulang dan mengatur ulang semua file. Halaman Pengembangan Utama harus berisi semua halaman ini dan hyperlink akan dibuat di setiap langkah.
• Tentang Halaman Gateway gRPC:-
Daftar semua kontributor harus ada di bagian tim Link cepat dan catatan rilis, blog terbaru akan ditambahkan untuk menarik perhatian pengguna agar mereka membaca berita gRPC-Gateway saat ini.
• Halaman Blog, Catatan Rilis, dan Tutorial:-
Saya merasa situs web itu harus memiliki opsi {i>blogging<i}. Agar berita dan rilis dapat disampaikan dengan mudah. Halaman tutorial akan memuat beberapa perbincangan dan artikel populer yang memperjelas API dan konsep gRPC-Gateway. Kontributor dapat menambahkan link tutorial di halaman tutorial.
Setelah menyelesaikan tugas di atas, perbarui perubahan yang sama di cabang v2 dan lakukan bahkan dengan cabang master gRPC-Gateway.
TUJUAN SEKUNDER PROJECT INI:-
Perubahan lain perlu dilakukan agar dokumentasi gRPC-Gateway lebih andal dan mudah dibaca:-
• Memperbaiki kesalahan tata bahasa dan Tipografi, serta mengatur dan menyelaraskan link dan postingan dalam situs di semua file gRPC-Gateway yang ada.
• Menambahkan lebih banyak dokumentasi dan konten jika diperlukan di gRPC-Gateway karena sebagian besar fitur memiliki dokumentasi yang sangat singkat seperti di bagian Dokumentasi pada situs di AWS, Latar Belakang, dan Penggunaan, dll.
• Memfaktorkan ulang cuplikan Go gRPC-Gateway sesuai dengan format Gofmt
Setelah menyelesaikan tugas di atas, perbarui perubahan yang sama di cabang v2 dan lakukan bahkan dengan cabang master gRPC-Gateway.
MENGAPA SAYA JADI ORANG YANG TEPAT UNTUK PROJECT INI:
Saya yakin saya adalah orang yang tepat untuk proyek ini karena:-
• Saya memiliki pengalaman dalam meningkatkan dokumentasi organisasi dan saya bisa menggunakan sistem kontrol versi apa pun, jadi menjalankan perintah di GitHub tidak akan menjadi masalah. • Selain itu, yang memotivasi saya adalah mengerjakan proyek yang menciptakan nilai bagi orang lain. Jika Anda ingin seseorang melakukan sesuatu dengan cara yang paling efisien, Anda mendokumentasikannya. Dengan mendokumentasikan proses, Anda memastikan efisiensi, konsistensi, dan ketenangan pikiran bagi siapa pun yang terlibat. • Saya familier dengan alur kerja dan codebase gRPC-Gateway karena saya berkontribusi pada gRPC-Gateway dari dua bulan terakhir dan mendapatkan 11 PR digabungkan.