Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.
Ringkasan proyek
- Organisasi open source:
- Cloud Native Computing Foundation (CNCF)
- Penulis teknis:
- Shriti
- Nama proyek:
- Meningkatkan dokumentasi SMI & mesh layanan terkait
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
Service Mesh Technology pada dasarnya bertujuan memberikan nilai bagi peningkatan jumlah layanan, dengan menangani semua kebutuhan keamanan, pengelolaan, dan pemantauan Anda. Service Mesh Interface (SMI) menentukan kumpulan API untuk kasus penggunaan mesh layanan yang paling umum (kebijakan traffic, telemetri, dan pergeseran) serta memungkinkan kompatibilitas antara mesh layanan, yang merupakan lapisan infrastruktur khusus untuk menangani komunikasi layanan-ke-layanan di lingkungan microservice. Standardisasi antarmuka ini akan memberikan pengalaman pengguna akhir yang lebih baik, dan oleh karena itu, menjadi tujuan masa depan untuk SMI dan mesh layanan terkait.
Status Saat Ini:
Panduan Pengguna: SMI adalah project sandbox yang relatif baru, yang didonasikan ke CNCF pada bulan April 2020. Akibatnya, proyek tidak memiliki dokumentasi pengguna akhir. Meshery adalah bidang pengelolaan layanan dengan tolok ukur performa untuk semua jenis layanan yang memfasilitasi adopsi, konfigurasi, operasi, dan pengelolaan performa berbagai mesh layanan serta menggabungkan pengumpulan dan tampilan metrik dari aplikasi yang berjalan di atas mesh layanan apa pun. Oleh karena itu, saya ingin memulai dengan panduan untuk Meshery, yang akan berfungsi sebagai titik awal bagi seluruh komunitas pengguna SMI.
Tutorial Pengguna: Di antara platform SMI yang ada: Aplikasi contoh, Learn Layer5, saat ini berfungsi sebagai perangkat pembelajaran untuk SMI dan sebagai aplikasi contoh untuk melakukan validasi spesifikasi SMI.Namun sebaliknya, proyek SMI sama sekali tidak memiliki tutorial pengguna akhir, yang merupakan hambatan serius karena sifat proyek yang sangat teknis. Meshery adalah aplikasi yang tepat untuk menunjukkan manfaat dan penggunaan SMI serta mesh layanan terkait. Itulah sebabnya saya akan menggunakannya sebagai alat dasar untuk menunjukkan fitur SMI.
Dokumentasi API: Tidak ada saat ini. SMI dan berbagai project terkait memiliki endpoint API yang ditentukan di platform; sebagai contoh, Meshery memiliki endpoint yang ditentukan di server.go (https://github.com/layer5io/meshery/blob/master/router/server.go), tetapi keduanya tidak diberi komentar atau didokumentasikan dengan baik secara eksternal. Hal ini dapat diatasi dengan dokumentasi API yang bermakna dan dapat ditingkatkan dengan menambahkan cara bagi pengguna untuk menguji endpoint dan melihat pratinjau fiturnya.
Analisis:
Tutorial Pengguna dibuat untuk memungkinkan pengguna terlibat dan menjalankan uji coba Perangkat Lunak. Mereka harus interaktif dan menarik secara estetis untuk mempertahankan perhatian pengguna dan yang paling penting, mudah digunakan.
Namun, untuk menulis atau menghosting Panduan Pengguna, format yang lebih matang direkomendasikan karena Panduan pengguna sering kali berfungsi sebagai panduan referensi atau tempat untuk memperbaiki masalah dengan cepat. Alih-alih interaktif, aplikasi harus terstruktur dengan baik dan fokus pada peningkatan kejelasan, koherensi, dan alur pengguna yang baik.
Solusi yang memungkinkan untuk hal ini adalah dengan membuat tutorial Pengguna terpisah menggunakan Google Codelabs dan Panduan Pengguna independen dengan bantuan Jekyll dan akhirnya mengintegrasikannya bersama dengan dokumentasi API untuk memberikan pengalaman yang menyeluruh kepada pengguna akhir dan kolaborator di masa mendatang.
Target Audiens: Project SPM menyediakan praktik deployment dan operasional, lingkungan pembelajaran, dan tolok ukur performa untuk semua project yang berada di bawahnya. Ini melayani individu dan organisasi.
Panduan Pengguna: Saya akan menargetkan pengguna pemula, tanpa asumsi bahwa pengguna memiliki pengetahuan IT yang sudah ada sebelumnya. Target: Alasan Pengguna Pemula: Digunakan terutama sebagai panduan Referensi yang lengkap, yang harus diperbarui seiring waktu. Hal ini akan mencakup penjelasan mendalam dan tips bermanfaat untuk memastikan pengguna memiliki semua informasi yang diperlukan untuk menyiapkan dan bekerja dengan mesh layanan. Panduan akan dibuat lebih menarik dan mudah digunakan dengan menambahkan video, gambar, screenshot, dan GIF, sesuai kebutuhan.
Tutorial Pengguna: Target: Pengguna Pemula Alasan: Fokusnya adalah membuat tutorial yang menarik dan menarik secara estetis untuk menarik perhatian pengguna dan memungkinkan uji coba software yang lancar, yang akan mengarah pada pemahaman yang lebih baik tentang Service Mesh Interface.
Dokumentasi Endpoint API: Target: Pengguna Lanjutan Alasan: Bagian ini berfokus pada penggunaan fitur mesh layanan yang lebih kompleks, yang lebih ditujukan untuk pengguna tingkat lanjut dengan pengetahuan IT dasar. Pengguna tingkat lanjut akan mencari tutorial singkat yang juga dapat digunakan sebagai panduan referensi, jika diperlukan. Dokumentasi Endpoint harus ditulis sedemikian rupa sehingga memudahkan update tanpa mengorbankan akurasi atau konsistensinya. Sebaiknya hal ini dilakukan secara otomatis.
Referensi: Tutorial Pengguna: Codelab Google Developers - Digunakan untuk membuat tutorial pengguna akhir yang interaktif dan komprehensif. Manfaat: - Dapat menghasilkan tutorial sandbox. - Memiliki pendekatan langsung. - Ditulis menggunakan Google Docs dan mendukung teks Markdown. - Dapat dipantau menggunakan Google Analytics - Traffic pengguna Mudah diamati. - Mudah digunakan. Menghasilkan tutorial yang estetis sehingga memungkinkan pengguna berinteraksi langsung dengan software tanpa investasi langsung.
Google Codelabs dapat ditingkatkan dan dengan mudah di-deploy menggunakan project CLaaT (Codelabs as a Thing) - Ini adalah program yang menawarkan alat command line yang digunakan untuk mengonversi tutorial yang ditulis dalam Google Dokumen menggunakan Markdown ke dalam format codelab (HTML).
Panduan Pengguna: Jekyll - Dokumentasi yang ada untuk meshery.io, yang dapat ditemukan di sini dihosting di Jekyll dan menggunakan tema Docsy Jekyll. Layanan ini menggunakan Markdown, liquid, HTML, dan CSS untuk membuat situs statis yang siap di-{i>host<i}, dan berjalan pada lingkungan pengembangan Ruby. Manfaat: - Dapat menghosting situs langsung dari repositori GitHub. - Project ini didukung dengan baik dengan komunitas yang sangat aktif - Panduan Pengguna dan peningkatan dapat dengan mudah ditambahkan ke dokumentasi SMI dan Meshery yang ada, tanpa harus repot bermigrasi ke platform lain.
Dokumentasi API: Swagger (atau Swaggo) akan digunakan untuk membuat dokumentasi API untuk SMI dan Meshery. Solusi ini merupakan solusi elegan untuk menulis dokumen API. Manfaat: - Dokumentasi dari Desain API Anda: Memastikan dokumentasi Anda tetap yang terbaru seiring perkembangan API. - Dokumentasi dari Desain API Anda: Dapat dihasilkan secara otomatis dari definisi API. - Mempertahankan Beberapa Versi Dokumentasi - Desain API yang Disesuaikan
Tujuan Proyek: - Menggunakan Google Developer Codelabs untuk membuat tutorial pengguna akhir yang interaktif untuk SMI dan mesh layanan terkait menggunakan Meshery sebagai alat. - Membuat panduan pengguna akhir, menggunakan Jekyll untuk mesh layanan. - Menggunakan Swagger untuk membuat dokumentasi endpoint API untuk SMI. - Mendorong komunitas proyek sehingga pengguna atau pengembang di masa depan dan saat ini dapat terus menambahkan materi dengan mudah di bawah panduan dan moderasi komunitas SMI.
Linimasa: Linimasa yang diusulkan dapat dilihat di sini: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
Struktur: Struktur yang diusulkan untuk Panduan Pengguna dapat ditemukan di sini: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
Mengapa Project ini? Komunitas mesh layanan berkembang sangat pesat, didukung oleh integrasi terbarunya sebagai project sandbox ke CNCF. Namun, proyek ini mengalami kelangkaan dokumentasi yang serius, baik bagi pengguna akhir maupun pengembang. Saya pernah mencoba berbagai mesh layanan sebelumnya, termasuk linkerD dengan aplikasi EmojiVoto, Istio dengan aplikasi bookinfo-nya, dan Hashicorp’s Consul. Saya juga telah mencoba pemisahan traffic SMI dan telah menerapkan berbagai aturan validasi pada konfigurasi mesh layanan saya. Proses pembelajarannya menarik, tetapi sangat teknis dan dapat menjadi hal yang sulit bagi pengguna baru serta developer, yang ingin mengambil langkah pertama ke komunitas mesh layanan atau memanfaatkan mesh layanan untuk proyek pribadi atau profesional mereka sendiri. Saya ingin menjembatani kesenjangan ini, yang hanya dapat dilakukan dengan panduan dan tutorial yang efisien dan didokumentasikan dengan baik.