Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- gRPC-Gateway
- {i>Technical writer <i}(Penulis teknis):
- iamrajiv
- Nama project:
- Memfaktorkan Ulang Situs Dokumen yang Ada untuk gRPC-Gateway
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
ABSTRAK:
Situs dokumen pengguna dirancang untuk membantu pengguna akhir menggunakan produk atau layanan. Situs dokumen pengguna yang baik sangat penting karena menyediakan sarana bagi pengguna untuk mempelajari cara menggunakan software, fitur, tips, trik, dan juga menyelesaikan masalah umum yang dialami saat menggunakan software. IA juga mengurangi biaya dukungan dan merupakan bagian dari identitas perusahaan produk. Situs dokumen pengguna yang baik adalah tanda kesehatan produk, tim developer. Tanpa situs dokumen pengguna yang baik, pengguna mungkin tidak tahu cara melakukan hal-hal di atas secara efektif dan efisien. Situs dokumen pengguna dapat memainkan peran penting dalam memastikan kesuksesan produk karena komunikasi yang baik adalah dan akan selalu menjadi inti dari bisnis atau produk apa pun. Dokumentasi yang baik hanya mengambil komunikasi tersebut dan memasukkannya ke dalam kerangka kerja yang dapat dikelola sehingga setiap orang dapat mencapai kesuksesan.
Pada saat penulisan ini, repositori gRPC-Gateway telah di-fork 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 mendapatkan panduan tentang cara menggunakan gRPC-Gateway. Namun, dokumentasi pengguna dan situs dokumen gRPC-Gateway saat ini sudah tidak berlaku dan tidak lengkap, dan komunitas gRPC-Gateway ingin menggunakan project ini untuk memfaktorkan ulang situs dokumen yang ada dan meningkatkan situs dokumennya agar pengguna akhir dapat memiliki pengalaman yang lancar saat menggunakan gRPC-Gateway.
STATUS SAAT INI:
Saat ini, situs dokumen gRPC-Gateway memiliki dua masalah utama:-
• Masalah pertama adalah situs dokumen yang buruk dan sudah tidak berlaku, yaitu gaya visual dan struktur situs serta tema yang digunakan sudah tidak berlaku, tidak lengkap, sulit dijelajahi atau menemukan informasi, tidak mencakup banyak fitur situs dokumen yang baik. Pemfaktoran ulang Situs Dokumen yang Ada dari gRPC-Gateway akan mencakup penataan gaya situs web, menambahkan fitur seperti penelusuran dokumen dll., meningkatkan UI situs web, mengatur tutorial dan contoh di sidebar yang tepat serta memperbarui diagram alir 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, perlu untuk memfaktorkan ulang dokumentasi, tutorial, dan contoh yang ada, dll. dari gRPC-Gateway yang dapat dilakukan dengan menghapus kesalahan tipografi dan tata bahasa di seluruh file, membuat penyelarasan yang tepat dari 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. Ini adalah sasaran sekunder saya dan akan melakukannya setelah saya menyelesaikan sasaran utama saya, yaitu menata gaya dan menyusun ulang situs Dokumen yang ada.
MENGAPA SITUS DOKUMEN SAYA MENJADI PERBAIKAN LEBIH DARI YANG SAAT INI?
Situs dokumen pengguna yang diusulkan akan disusun untuk meningkatkan dan memastikan efisiensi, konsistensi, dan ketenangan bagi pengguna akhir. Hal ini akan memberikan tampilan dan UI yang lebih baik dengan bagian dan fitur yang ditata dengan baik serta berisi panduan tertulis dan diagram alir serta gambar terkait.
Dokumentasi gRPC-Gateway memberikan deskripsi yang baik tentang metode dan contoh. Namun, tema ini masih menggunakan tema Jekyll lama dan saat ini kita memiliki tema Jekyll SSG (Static Site Generator) yang lebih baik. Selain itu, perlu adanya penyusunan ulang halaman dan membuatnya lebih berguna bagi pengguna dengan menambahkan contoh dan tutorial baru serta memperbarui dan menulis ulang konten sebelumnya.
STRUKTUR DAN ROADMAP TUJUAN DAN IDE YANG DIUSULKAN:
TUJUAN UTAMA PROJEK INI:-
Sasaran dan ide di atas dapat diterapkan dengan cara berikut:-
Mengubah tema Current Jekyll ke tema yang lebih baik dan kuat. Alasan menggunakan tema Jekyll lagi adalah agar pengelola dapat berkontribusi dan memahami alur kerja project dengan mudah karena mereka sudah mengetahui framework dan tema Jekyll yang ada yang mirip dengan tema Jekyll baru.
Setelah melihat berbagai tema Jekyll di internet, saya menemukan tema https://idratherbewriting.com/documentation-theme-jekyll/ yang paling cocok untuk situs dokumen gRPC-Gateway karena fitur berikut:
• Markdown:- Agar penulis teknis tidak perlu mengkhawatirkan penginstalan. Mereka dapat menulis dengan mudah dalam file .md. Siapa saja dapat mengklik tombol edit yang ditampilkan di situs (fitur baru) dan berkontribusi (mengedit/menyarankan perubahan untuk halaman di GitHub) untuk membuatnya lebih baik. Tindakan ini akan melibatkan pengguna untuk menambahkan konten baru atau mengedit konten guna meningkatkan kualitasnya.
• Penelusuran Dokumentasi:- Pengguna harus memiliki kotak penelusuran agar mereka dapat menemukan konten yang relevan dengan mudah dan cepat.
• Bagian Komentar:- Pengguna mungkin memiliki opsi untuk memberikan komentar dan membagikan pendapat mereka tentang postingan dan tutorial. Mereka dapat membaca tampilan orang lain pada dokumentasi project.
• Catatan Rilis dan Blog Baru:- Situs harus diperbarui dengan postingan blog dan berita baru tentang pengembangan dan roadmap saat ini. Jadi, jenis {i>blogging<i} harus ada di halaman muka.
• Pengembangan Cepat:- Sebagian besar framework SSG (Static Site Generator) berjalan di server dan perubahan pada file akan segera ditampilkan di UI. Selain itu, proses deploy dan build harus mudah. Di masa mendatang, jika kita ingin mengubah {i>framework<i}, kita akan menggunakan. Kemudian, Anda akan dapat melakukannya dengan mudah. Sebagian besar framework mendukung penulisan Markdown sehingga hanya memindahkan file .md dan beberapa perubahan sudah cukup.
Di sini, saya memisahkan halaman situs yang ada menjadi bagian dan halaman situs baru :
• Halaman Landing:-
Halaman landing harus menunjukkan fitur utama gRPC-Gateway.
- Memulai gRPC-Gateway (dialihkan ke panduan pengguna)
- Petunjuk Penginstalan Sederhana (perintah singkat)
- Alasan menggunakan gRPC-Gateway
- Project yang 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 gRPC-Gateway:-
- Panduan penginstalan.
- Mulai cepat dengan gRPC-Gateway.
• Halaman Panduan Developer gRPC-Gateway:-
Panduan Pengembangan, Panduan kontribusi, penyiapan Git, Kode Etik, Penyiapan dokumentasi, Alur kerja pengembangan, dll. mengarah ke halaman serupa di dalamnya. Jadi, pemfaktoran ulang dan pengaturan ulang semua file diperlukan. 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 berinteraksi dengan pengguna agar mereka membaca berita gRPC-Gateway terkini.
• Halaman Blog, Catatan Rilis, dan Tutorial:-
Saya merasa bahwa situs harus memiliki opsi blog. Jadi, berita dan rilis dapat disampaikan dengan mudah. Halaman tutorial akan berisi beberapa diskusi dan artikel populer yang menjelaskan API dan konsep gRPC-Gateway. Kontributor dapat menambahkan link tutorial mereka di halaman tutorial.
Setelah menyelesaikan tugas di atas, perbarui perubahan yang sama di cabang v2 dan buat sama dengan cabang master gRPC-Gateway.
SASARAN TAMBAHAN PROJEK INI:-
Perubahan lain perlu dilakukan untuk membuat dokumentasi gRPC-Gateway lebih andal dan mudah dibaca:-
• Memperbaiki kesalahan tata bahasa, Tipografi, serta mengatur dan menyelaraskan link dan postingan di 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 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 buat sama dengan cabang master gRPC-Gateway.
MENGAPA SAYA ORANG YANG TEPAT UNTUK PROJEK INI:
Saya yakin saya adalah orang yang tepat untuk project ini karena:-
• Saya memiliki pengalaman sebelumnya dalam meningkatkan dokumentasi organisasi dan saya dapat menggunakan sistem kontrol versi apa pun, sehingga menjalankan perintah di GitHub tidak akan menjadi masalah. • Selain itu, hal yang mendorong saya adalah mengerjakan proyek yang menciptakan nilai bagi banyak orang. Saya percaya bahwa jika Anda ingin seseorang melakukan sesuatu dengan cara yang paling efisien, Anda harus mendokumentasikannya. Dengan mendokumentasikan proses Anda, Anda memastikan efisiensi, konsistensi, dan ketenangan pikiran bagi siapa pun yang terlibat. • Saya sudah familier dengan alur kerja dan codebase gRPC-Gateway karena saya berkontribusi untuk gRPC-Gateway dari dua bulan terakhir dan berhasil menggabungkan 11 PR.