Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- Cloud Native Computing Foundation (CNCF)
- Penulis teknis:
- Shriti
- Nama project:
- Meningkatkan dokumentasi SMI & mesh layanan terkait
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
Teknologi Service Mesh pada dasarnya bertujuan untuk memberikan nilai tambah pada semakin banyaknya layanan, dengan menangani semua kebutuhan keamanan, pengelolaan, dan pemantauan Anda. Antarmuka Mesh Layanan (SMI) menentukan serangkaian API untuk kasus penggunaan mesh layanan yang paling umum (kebijakan traffic, telemetri, dan pergeseran) serta memungkinkan kompatibilitas antar-mesh layanan, yang merupakan lapisan infrastruktur khusus untuk menangani komunikasi layanan ke layanan di lingkungan microservice. Standarisasi antarmuka ini akan memberikan pengalaman pengguna akhir yang lebih baik, sehingga menjadi sasaran masa depan untuk SMI dan mesh layanan terkait.
Status Saat Ini:
Panduan Pengguna: SMI adalah project sandbox yang relatif baru, yang disumbangkan ke CNCF pada April 2020. Akibatnya, proyek tersebut kurang memiliki dokumentasi pengguna akhir. Meshery adalah platform pengelolaan layanan dengan benchmark 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, project SMI sama sekali tidak memiliki tutorial pengguna akhir, yang merupakan hambatan serius karena sifat project yang sangat teknis. Meshery adalah aplikasi yang tepat untuk menunjukkan manfaat dan penggunaan SMI serta mesh layanan terkait. Oleh karena itu, saya akan menggunakannya sebagai alat dasar untuk menampilkan fitur SMI.
Dokumentasi API: Saat ini tidak ada. 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 tidak dikomentari 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-nya dan melihat pratinjau fiturnya.
Analisis:
Tutorial Pengguna dibuat untuk memungkinkan pengguna berinteraksi dan menjalankan pengujian Software. Aplikasi harus interaktif dan menarik secara estetika untuk mempertahankan perhatian pengguna dan yang terpenting, mudah digunakan.
Namun, untuk menulis atau menghosting Panduan Pengguna, sebaiknya gunakan format yang lebih matang karena Panduan pengguna sering kali berfungsi sebagai panduan referensi atau tempat untuk mendapatkan solusi cepat atas masalah. Alih-alih interaktif, alur harus disusun dengan baik dan berfokus pada peningkatan kejelasan, koherensi, dan alur penggunaan yang baik.
Solusi yang mungkin untuk hal ini adalah membuat tutorial Pengguna terpisah menggunakan Google Codelab dan Panduan Pengguna independen dengan bantuan Jekyll, lalu akhirnya mengintegrasikannya bersama dengan dokumentasi API untuk memberikan pengalaman yang menyeluruh kepada pengguna akhir dan kolaborator di masa mendatang.
Target Audiens: Project SMI menyediakan praktik deployment dan operasional, lingkungan pembelajaran, dan tolok ukur performa untuk semua project di bawahnya. Platform ini melayani individu dan organisasi.
Panduan Pengguna: Saya akan menargetkan pengguna pemula, tanpa asumsi bahwa pengguna sudah memiliki pengetahuan IT sebelumnya. Target: Pengguna Pemula Alasan: Digunakan terutama sebagai panduan Referensi yang luas, yang perlu diperbarui seiring waktu. Panduan ini akan mencakup penjelasan mendalam dan tips bermanfaat, untuk memastikan bahwa pengguna memiliki semua informasi yang diperlukan untuk menyiapkan dan menggunakan mesh layanan. Panduan akan dibuat lebih menarik dan mudah digunakan dengan menambahkan video, gambar, screenshot, dan GIF, jika diperlukan.
Tutorial Pengguna: Target: Pengguna Pemula Alasan: Fokusnya adalah membuat tutorial menarik dan menarik secara estetika untuk menarik perhatian pengguna dan memungkinkan pengujian software yang lancar, yang akan menghasilkan pemahaman yang lebih baik tentang Antarmuka Service Mesh.
Dokumentasi Endpoint API: Target: Pengguna Lanjutan Alasan: Bagian ini berfokus pada penggunaan fitur mesh layanan yang lebih kompleks, yang lebih sesuai bagi pengguna lanjutan dengan tingkat pengetahuan IT dasar. Pengguna tingkat lanjut akan mencari tutorial ringkas yang juga dapat digunakan sebagai panduan referensi, jika diperlukan. Dokumentasi Endpoint harus ditulis dengan cara tersebut, sehingga memudahkan pembaruan tanpa mengorbankan akurasi atau konsistensinya. Sebaiknya proses ini bersifat otomatis.
Referensi: Tutorial Pengguna: Codelab Google Developers - Digunakan untuk membuat tutorial pengguna akhir yang interaktif dan komprehensif. Manfaat: - Dapat membuat tutorial sandbox. - Memiliki pendekatan praktis. - Ditulis menggunakan Google Dokumen dan mendukung teks Markdown. - Dapat dipantau menggunakan Google Analytics - Mudah diamati traffic pengguna. - Mudah digunakan. Membuat tutorial yang estetis dan menarik, sehingga pengguna dapat berinteraksi langsung dengan software tanpa investasi langsung.
Google Codelab dapat ditingkatkan dan di-deploy dengan mudah menggunakan project CLaaT (Codelabs as a Thing) - Ini adalah program yang menawarkan alat command line yang digunakan untuk mengonversi tutorial yang ditulis di 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. Ia menggunakan Markdown, liquid, HTML, dan CSS untuk menghasilkan situs statis yang siap dihosting dan berjalan di lingkungan pengembangan Ruby. Manfaat: - Dapat menghosting situs langsung dari repositori GitHub. - Ini adalah Project yang 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. Ini adalah solusi yang elegan untuk menulis dokumen API. Manfaat: - Dokumentasi dari Desain API Anda: Memastikan dokumentasi Anda tetap terbaru seiring perkembangan API. - Dokumentasi dari Desain API Anda: Dapat dibuat secara otomatis dari definisi API. - Mempertahankan Beberapa Versi Dokumentasi - Desain API yang Disesuaikan
Sasaran Project: - Gunakan Codelab Google Developer 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. - Buat project yang didorong oleh komunitas sehingga pengguna atau developer saat ini dan mendatang dapat dengan mudah terus menambahkannya di bawah bimbingan dan moderasi komunitas SMI.
Linimasa: Linimasa yang diusulkan dapat ditemukan 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 service mesh berkembang dengan kecepatan kilat, yang dimungkinkan oleh integrasi terbarunya sebagai project sandbox ke dalam CNCF. Namun, project ini mengalami kekurangan dokumentasi yang serius, baik untuk pengguna akhir maupun developer. Saya telah mencoba berbagai mesh layanan sebelumnya, termasuk linkerD dengan aplikasi EmojiVoto, Istio dengan aplikasi bookinfo-nya, dan Consul Hashicorp. 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 membuat pengguna baru serta developer yang ingin mengambil langkah pertama mereka ke dalam komunitas mesh layanan atau menggunakan mesh layanan untuk project pribadi atau profesional mereka sendiri merasa enggan. Saya ingin menjembatani kesenjangan ini, yang hanya dapat dilakukan dengan panduan dan tutorial yang efisien dan didokumentasikan dengan baik.