Bu sayfa, Google Dokümanlar Sezonu için kabul edilen bir teknik yazı projesinin ayrıntılarını içerir.
Proje özeti
- Açık kaynak kuruluşu:
- Bulutta Yerel Bilişim Vakfı (CNCF)
- Teknik yazar:
- Şriti
- Projenin adı:
- SMI ve ilgili hizmet ağları ile ilgili belgeleri iyileştirin
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Service Mesh Teknolojisi temel olarak tüm güvenlik, yönetim ve izleme ihtiyaçlarınızı karşılayarak gittikçe artan hizmetlere değer sağlamayı amaçlar. Hizmet Ağı Arayüzü (SMI), en yaygın hizmet ağı kullanım alanları (trafik politikası, telemetri ve geçiş) için bir dizi API tanımlar ve mikro hizmet ortamında hizmetten hizmete iletişimi yönetmek için özel altyapı katmanları olan hizmet ağları arasında uyumluluğu sağlar. Bu arayüzlerin standartlaştırılması, daha gelişmiş bir son kullanıcı deneyimi sağlayacağından SMI ve ilgili hizmet ağları için gelecekte bir hedef olacaktır.
Mevcut Durum:
Kullanıcı Rehberleri: SMI, Nisan 2020'de CNCF'ye bağışlanan nispeten yeni bir korumalı alan projesidir. Sonuç olarak, projede son kullanıcı belgeleri eksiktir. Meshery, farklı hizmet ağlarının performansının benimsenmesini, yapılandırılmasını, işletilmesini ve yönetilmesini kolaylaştıran her türlü hizmetin performans karşılaştırmasına sahip bir hizmet yönetim düzlemidir. Ayrıca, herhangi bir hizmet ağının üzerinde çalışan uygulamalardan metriklerin toplanıp görüntülenmesini içerir. Bu nedenle, Meshery için bir rehberle başlamak istiyorum. Bu rehber, tüm SMI kullanıcı topluluğu için bir başlangıç noktası olacaktır.
Kullanıcı Eğiticileri: Mevcut SMI platformları arasında: Learn tier5 örnek uygulaması şu anda SMI için bir öğrenme cihazı ve SMI spesifikasyonu doğrulaması yapmak için örnek uygulama olarak hizmet verir. Ancak SMI projelerinin son kullanıcı eğitimleri eksikliği tamamen son kullanıcı eğitimlerinden yoksun olur. Bu da projelerin son derece teknik yapısı nedeniyle ciddi bir aksaklığa yol açar. Meshery, SMI ve ilgili hizmet ağlarının faydalarını ve kullanımını gösteren mükemmel bir uygulama. Bu nedenle, SMI'nın özelliklerini sergilemek için onu temel araç olarak kullanacağım.
API Belgeleri: Şu anda mevcut değil. SMI ve ilgili çeşitli projelerin API uç noktaları bir platformda tanımlanmıştır. Örneğin, Meshery'nin uç noktaları server.go (https://github.com/layer5io/meshery/blob/master/router/server.go) adresinde tanımlanmıştır ancak bunlar harici olarak iyi yorumlanmamıştır veya belgelenmemiştir. Bu sorun, API'lere ilişkin anlamlı belgelerle çözülebilir ve kullanıcıların uç noktalarını test etmeleri ve özelliklerini önizlemeleri için yöntemler ekleyerek geliştirilebilir.
Analiz:
Kullanıcı Eğiticileri, kullanıcının etkileşimde bulunması ve Yazılım'ı test etmesi için hazırlanır. Kullanıcının ilgisini çekmek için etkileşimli ve estetik açıdan çekici olmaları, en önemlisi de kullanım kolaylığı sağlamaları gerekir.
Bununla birlikte, Kullanıcı Rehberleri yazarken veya barındırırken, kullanıcı rehberleri genellikle bir başvuru kılavuzu ya da sorunların hızlı bir şekilde çözülmesini sağlayacak bir yer görevi gördüğü için daha kapsamlı bir biçim kullanmanız önerilir. Bunların etkileşimli olmak yerine iyi yapılandırılmış olmaları ve netliği, tutarlılığı ve iyi kullanıcı akışını iyileştirmeye odaklanmaları gerekir.
Bu sorunun olası bir çözümü, Google Codelabs'i kullanarak ayrı Kullanıcı öğreticileri hazırlamak ve Jekyll'in yardımıyla bağımsız bir Kullanıcı Rehberi hazırlamak ve son olarak da bu eğitimleri API belgeleriyle birlikte entegre ederek hem son kullanıcıya hem de gelecekteki ortak çalışanlara kapsamlı bir deneyim sunmaktır.
Hedef Kitle: SMI projeleri, altlarındaki tüm projeler için dağıtım ve operasyon uygulamaları, öğrenme ortamları ve performans karşılaştırmaları sağlar. Hem bireylere hem de kuruluşlara hizmet verir.
Kullanıcı Kılavuzları: Kullanıcı tarafında önceden BT bilgisi varsayımı olmadan yeni başlayan kullanıcıları hedefleyeceğim. Hedef: Yeni Başlayan Kullanıcılar Neden: Zamanla güncellenmesi gerekecek, kapsamlı bir Başvuru kılavuzu olarak kullanılmıştır. Bu bölüm, kullanıcının bir hizmet ağını kurmak ve kullanmak için ihtiyaç duyduğu tüm bilgilere sahip olduğundan emin olmak amacıyla ayrıntılı açıklamalar ve faydalı ipuçları içerir. Gerektiğinde videolar, resimler, ekran görüntüleri ve GIF'ler ekleyerek Rehber daha ilgi çekici ve kullanıcı dostu hale getirilecek.
Kullanıcı Eğiticileri: Hedef: Yeni Kullanıcılar Neden: Kullanıcıların dikkatini çekmek için eğitimlerin ilgi çekici ve estetik açıdan çekici olmasını sağlamak ve Hizmet Ağı Arayüzünün daha iyi anlaşılmasını sağlamak amacıyla yazılımı sorunsuz bir şekilde test etmektir.
API Uç Noktası dokümanı: Hedef: İleri Düzey Kullanıcılar Neden: Bu bölüm, temel düzeyde BT bilgisine sahip ileri düzey kullanıcıların işine yarayan hizmet ağının daha karmaşık özelliklerini kullanmaya odaklanıyor. İleri düzey kullanıcılar, gerekirse referans rehber olarak da kullanılabilecek kısa ve öz eğitimler aramaktadır. Uç nokta belgeleri, doğruluğundan veya tutarlılığından ödün vermeden kolayca güncellenebilecek şekilde yazılmalıdır. Bu işlemin otomatik olması tercih edilir.
Kaynaklar: Kullanıcı Eğiticileri: Google Developers Codelab - Etkileşimli ve kapsamlı son kullanıcı eğitimleri oluşturmak için kullanılır. Faydaları: - Korumalı alan eğiticileri oluşturabilir. - Pratik bir yaklaşıma sahiptir. - Google Dokümanlar kullanılarak yazılmıştır ve Markdown metnini destekler. - Google Analytics kullanılarak izlenebilir - Kullanıcı trafiğini gözlemlemek kolaydır. - Kullanımı kolaydır. Kullanıcının doğrudan herhangi bir yatırım yapmadan yazılımla doğrudan etkileşime girmesini sağlayan, estetik açıdan göze hitap eden eğitici videolar oluşturur.
Google Codelabs, CLaaT (Thing Olarak Codelabs) projesi kullanılarak geliştirilip kolayca dağıtılabilir. Bu program, Markdown kullanılarak Google Dokümanlar'da yazılmış eğiticileri codelab (HTML) biçimine dönüştürmek için kullanılan bir komut satırı aracı sunan bir programdır.
Kullanıcı Kılavuzları: Jekyll: Meshery.io'nun burada yer alan mevcut dokümanları Jekyll'de barındırılmaktadır ve Docsy Jekyll temasını kullanmaktadır. Barındırmaya hazır statik web siteleri üretmek için Markdown, likit, HTML ve CSS kullanır ve bir Ruby geliştirme ortamında çalışır. Avantajları: - Doğrudan GitHub depolarından site barındırabilir. - Bu, çok etkin bir topluluğa sahip, iyi desteklenen bir proje - Kullanıcı Rehberleri ve geliştirmeler, başka bir platforma geçiş yapmanıza gerek kalmadan mevcut SMI ve Meshery belgelerine kolayca eklenebilir.
API Belgeleri: SMI ve Meshery için API belgeleri oluşturmak amacıyla Swagger (alternatif olarak Swaggo) kullanılır. API dokümanları yazmak için şık bir çözümdür. Faydaları: - API Tasarımınızdan Belgeler: API'niz geliştikçe belgelerinizin güncel kalmasını sağlar. - API Tasarımınızdan Belgeler: API tanımlarından otomatik olarak oluşturulabilir. - Birden Fazla Belge Sürümü Kullanma - Özelleştirilmiş API Tasarımları
Proje Hedefleri: - Meshery'yi bir araç olarak kullanarak SMI ve ilgili hizmet ağları için etkileşimli son kullanıcı eğitimleri oluşturmak üzere Google Developer Codelabs'i kullanın. - Hizmet ağları için Jekyll'i kullanarak bir son kullanıcı kılavuzu oluşturun. - Swagger'ı kullanarak SMI için API uç nokta belgeleri oluşturun. - Gelecekteki ve mevcut kullanıcıların veya geliştiricilerin SMI topluluğunun rehberliğinde ve denetiminde kolayca ekleme yapmaya devam edebilmesi için proje topluluğunu yönlendirmelidir.
Zaman çizelgesi: Önerilen zaman çizelgesini şu adreste bulabilirsiniz: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
Yapı: Kullanıcı Rehberi için önerilen yapıya şu adresten ulaşabilirsiniz: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
Neden bu Proje? Yakın zamanda CNCF'ye bir korumalı alan projesi olarak entegre edilmesiyle mümkün olan hizmet ağı topluluğu, ışık hızında büyüyor. Ancak bu projede, hem son kullanıcılar hem de geliştiriciler için ciddi bir belge eksikliği yaşanıyor. Geçmişte EmojiVoto uygulaması ile linkerD, kitap bilgileri uygulaması olan Istio ve Hashicorp'un konsolosluğu gibi çeşitli hizmet ağları ile çalıştım. SMI trafik bölme işlemini de denedim ve hizmet ağı yapılandırmamda çeşitli doğrulama kuralları uyguladım. Öğrenme süreci etkileyici olmakla birlikte oldukça tekniktir. Hizmet ağı topluluğuna ilk adımlarını atmayı veya kendi kişisel ya da profesyonel projeleri için hizmet ağlarını kullanmayı amaçlayan geliştiricilerin yanı sıra yeni kullanıcılar da ertelenebilir. Bu açığı kapatmak istiyorum; ancak verimli ve iyi belgelenmiş kılavuzlar ve eğitimlerle yapılabilir.