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:
- gRPC-Ağ Geçidi
- Teknik yazar:
- iamrajiv
- Projenin adı:
- gRPC Ağ Geçidinin Mevcut Dokümanlar Sitesini Yeniden Düzenleme
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
ÖZET:
Kullanıcı Dokümanlar sitesi, son kullanıcıların bir ürün veya hizmeti kullanmasına yardımcı olmak üzere tasarlanmıştır. İyi kullanıcı dokümanları sitesi, kullanıcılara, yazılımı, özelliklerini, ipuçlarını, püf noktalarını öğrenmeleri ve yazılım kullanılırken karşılaşılan yaygın sorunları çözmeleri için bir yol sağladığından çok önemlidir. Ayrıca destek maliyetini azaltır ve ürünün kurumsal kimliğinin bir parçasıdır. Kullanıcı dokümanlarının iyi olması ürünün, yani geliştirici ekibinin sağlıklı olduğunu gösterir. İyi bir kullanıcı dokümanları sitesi olmadan, kullanıcı yukarıdakilerin nasıl etkili ve verimli bir şekilde yapılacağını bilemeyebilir. Kullanıcı dokümanları sitesi, bir ürünün başarılı olmasında çok önemli bir rol oynayabilir. Çünkü başarılı iletişim, her zaman işletme veya ürünün merkezinde yer alır ve mükemmel belgeler bu iletişimi alır ve herkesin başarıya ulaşmak için erişebileceği yönetilebilir bir çerçeveye sokar.
Bu yazı hazırlandığı sırada, gRPC-Gateway deposu yaklaşık 1.200 kez çatallanmış ve bu depoya 184 kişi katkıda bulunmuş. Bu, dünyanın her yerinden pek çok kişinin gRPC Ağ Geçidi'ni kullandığını ve gRPC-Gateway'in nasıl kullanılacağıyla ilgili yol gösterici bilgiler için kullanıcı dokümanlarını okumak isteyebileceğini gösteriyor. Ancak, gRPC-Gateway kullanıcı dokümanları ve dokümanlar sitesi şu anda eski ve eksiktir ve gRPC-Gateway topluluğu, son kullanıcıların gRPC-Gateway kullanırken sorunsuz bir deneyim yaşamasını sağlamak için mevcut dokümanlar sitesini yeniden düzenlemek ve dokümanlar sitesini iyileştirmek için bu projeyi kullanmak istemektedir.
MEVCUT DURUM:
Şu anda, gRPC-Gateway dokümanlar sitesinde iki önemli sorun vardır:-
• İlk sorun kötü ve eski Google Dokümanlar web sitesidir; sitenin stili ve yapısı eski, eksik, gezinmesi veya bilgiye ulaşmanın zor olması, iyi Dokümanlar web sitelerinin birçok özelliğini kapsamaz. gRPC Ağ Geçidi'nin Mevcut Dokümanlar Sitesinin yeniden düzenlenmesi, web sitesinin stilinin değiştirilmesi, doküman arama gibi özelliklerin eklenmesi, web sitesinin kullanıcı arayüzünün iyileştirilmesi, eğiticiler ile örneklerin uygun bir kenar çubuğunda düzenlenmesi ve yeni bir tane tasarlayarak mevcut akış şemaları ile resimlerinin güncellenmesi gibi konuları içerir. Bu benim asıl hedefim olacak ve daha çok, mevcut Dokümanlar sitesinin stil ve yeniden yapılandırılmasına odaklanacağım.
• İkinci sorun, gRPC Ağ Geçidi ile ilgili mevcut dokümanları, eğiticileri, örnekleri vb. yeniden düzenleme ihtiyacıdır. Bu işlem, dosyalardaki yazım ve dil bilgisi hatalarının kaldırılması, Go snippet'lerinin düzgün bir şekilde hizalanması ve Go snippet'lerinin Gofmt biçimlerine göre yeniden düzenlenmesi yoluyla yapılabilir. Ayrıca, gerekirse daha fazla doküman, eğitim ve örnek ekleyebiliriz ya da mevcut dosyaları yeniden düzenledikten sonra yeniden kullanabiliriz. Bu, ikincil hedefim ve birincil hedefimi (mevcut Dokümanlar sitesinin stilini belirleme ve yeniden yapılandırma) tamamladıktan sonra yapacağım.
ÖNERİLEN DOKÜMANLAR SİTE NEDEN MEVCUT DOKÜMAN ÜZERİNDEN İYİLEŞTİRMELİDİR?
Teklif edilen kullanıcı dokümanları web sitesi, son kullanıcı için verimliliği, tutarlılığı ve huzurunu iyileştirmek ve sağlamak üzere yapılandırılacak. Yazılı kılavuzlar, bunlarla ilişkili akış şemaları ve resimler içeren iyi tasarlanmış bölümler ve özelliklerle daha iyi bir görünüm ve kullanıcı arayüzü sunacak.
gRPC-Gateway belgelerinde yöntem ve örneğin iyi bir açıklama verilmiştir. Ancak hâlâ eski Jekyll temasını kullanıyor ve modern günlerde SSG (Statik Site Oluşturucu) Jekyll temaları daha iyi durumda. Ayrıca sayfaların yeniden yapılandırılması ve yeni örnekler ve öğreticiler ekleyerek, önceki içerikleri güncelleyip yeniden yazarak sayfanın kullanıcılar için daha kullanışlı hale getirilmesine ihtiyaç vardır.
ÖNERİLEN HEDEFLERİN VE FİKİRLERİN YAPISI VE YOL HARİASI:
BU PROJENİN BİRİNCİL HEDEFİ:-
Yukarıdaki hedefler ve fikirler şu şekillerde uygulanabilir:
Geçerli Jekyll teması daha iyi ve sağlam bir temaya geçiriliyor. Jekyll temalarını tekrar kullanma nedenimiz, bakım görevlilerinin yeni Jekyll temasına benzeyen mevcut Jekyll çerçevesini ve temasını zaten bildiği için projenin iş akışına katkıda bulunmalarının ve bu iş akışını anlamalarının kolay olmasıdır.
İnternet'te farklı Jekyll temalarını inceledikten sonra, gRPC-Gateway dokümanları sitesi için bu https://idratherbewriting.com/documentation-theme-jekyll/ tema paketini en uygun özellik olarak buldum:
• Markdown:- Böylece teknik yazarlar kurulum konusunda endişelenmez. Yalnızca .md dosyasına yazabilirler. Herkes web sitesinde gösterilen düzenle düğmesini (yeni özellik) tıklayabilir ve daha iyi hale getirmek için (GitHub'da sayfa için düzenleme/değişiklikler önermek) katkıda bulunabilir. Bu, kullanıcıları yeni içerik eklemeye veya iyileştirmek için içeriği düzenlemeye teşvik eder.
• Belge Arama: Kullanıcının, alakalı içerikleri kolay ve hızlı bir şekilde bulabilmesi için bir arama kutusu olmalıdır.
• Yorumlar Bölümü:- Kullanıcı, yayınlarda ve eğiticilerle ilgili yorum yapma ve görüşlerini paylaşma seçeneğine sahip olabilir. Proje belgelerindeki diğer kişilerin görüşlerini okuyabilirler.
• Yeni Sürüm Notları ve Bloglar:- Web sitesi, yeni blog yayınlarının yanı sıra mevcut geliştirme ve yol haritasıyla ilgili haberlerle güncellenmelidir. Açılış sayfasında bir blog türü bulunmalıdır.
• Hızlı Geliştirme: SSG (Statik Site Oluşturucu) çerçevelerinin çoğu sunucuda çalışır ve dosyadaki değişiklikler kullanıcı arayüzüne hemen yansıtılır. Ayrıca dağıtım ve derleme işlemleri de kolay olmalıdır. Gelecekte çerçeveyi değiştirmek istediğimizde bunu kullanırız. Sonra kolay olmalıdır. Çerçevelerin çoğu Markdown yazmayı desteklediğinden .md dosyalarını ve az sayıda değişikliği taşımak yeterli olacaktır.
Burada, mevcut web sitesi sayfalarını yeni web sitesi bölümlerine ve sayfalarına ayırıyorum :
• Açılış Sayfası:-
Açılış sayfası, gRPC-Ağ geçidinin temel özelliklerini göstermelidir.
- gRPC-Gateway'i kullanmaya başlama (kullanıcı rehberine yönlendirin)
- Basit Yükleme talimatları (kısa komutlar)
- gRPC-Gateway'i neden kullanmalısınız?
- gRPC-Gateway kullanan proje
Yani temel fikir uzun açıklama yazmak yerine, açılış sayfasında ana noktaları göstermek ve ayrıntılara gidilecek bağlantıyı sunmaktır.
• gRPC-Ağ Geçidi Kullanıcı Kılavuzu Sayfası:-
- Kurulum kılavuzu.
- gRPC-Gateway ile hızlı başlangıç.
• gRPC-Gateway Geliştirici Kılavuzu Sayfası:-
Geliştirme Kılavuzu, Katkı kılavuzu, Git kurulumu, Davranış Kuralları, Doküman kurulumu, Geliştirme iş akışı vb. kaynaklar, içerideki benzer sayfalara işaret etmektedir. Bu nedenle tüm dosyaların yeniden düzenlenmesi ve düzenlenmesi gerekir. Ana Geliştirme sayfası bu sayfaların tümünü içermelidir ve her adımda köprü oluşturulur.
• gRPC Ağ Geçidi Sayfası Hakkında:-
Tüm katkıda bulunanların listesi ekip bölümlerinde bulunmalıdır Hızlı bağlantılar ve sürüm notları; kullanıcının güncel gRPC-Gateway haberlerini okumasını sağlamak üzere en son bloglar eklenecektir.
• Bloglar, Sürüm Notları ve Eğiticiler Sayfası:-
Web sitesinde blog verme seçeneği olması gerektiğini düşünüyorum. Böylece haberler ve yayınlar kolayca iletilebilir. Eğitim sayfası, gRPC-Gateway API'lerini ve kavramlarını açıklığa kavuşturan bazı popüler konuşmaları ve makaleleri içerecektir. Katkıda bulunanlar eğitim sayfasına kendi eğitim bağlantılarını ekleyebilirler.
Yukarıdaki görevi tamamladıktan sonra aynı değişiklikleri v2 dalında güncelleyin ve gRPC-Gateway'in ana dalıyla eşit şekilde uygulayın.
BU PROJENİN İKİNCİL HEDEFİ:
gRPC Ağ Geçidi belgelerinin daha sağlam ve okunabilir olması için başka değişikliklerin yapılması gerekir:-
• gRPC-Gateway'in mevcut tüm dosyalarında dil bilgisi ve yazım hatalarını düzeltme, sitedeki bağlantı ve yayınları düzenleyip uyumlu hale getirme.
• Özelliklerin çoğu, sitenin AWS, Arka Plan ve Kullanım gibi Belgeler bölümü gibi çok kısa dokümanlara sahip olduğundan, gerekirse gRPC-Gateway'e daha fazla belge ve içerik ekleme.
• Go snippet'leri gRPC-Gateway'i Gofmt biçimlerine göre yeniden düzenleme
Yukarıdaki görevi tamamladıktan sonra aynı değişiklikleri v2 dalında güncelleyin ve gRPC-Gateway'in ana dalıyla eşit şekilde uygulayın.
NEDEN BU PROJE İÇİN DOĞRU KİŞİSİM?
Bu proje için doğru kişi olduğuma inanıyorum çünkü:-
• Kuruluşların dokümanlarını geliştirme konusunda deneyime sahibim ve herhangi bir sürüm denetim sistemini kullanabilirim; bu yüzden, GitHub'da komut çalıştırmak sorun olmayacak. • Ayrıca, insanlara değer katan projelerde çalışmak beni motive ediyor. Birinin bir şeyi mümkün olan en verimli şekilde yapmasını istiyorsanız onu belgelemelisiniz. Süreçlerinizi belgeleyerek projeye dahil olan herkesin verimlilik ve tutarlılık elde etmesini ve gönül rahatlığını sağlarsınız. • Son iki ayda gRPC-Gateway'e katkıda bulunduğum ve 11 PR'yi birleştirdiğim için gRPC-Gateway iş akışına ve kod tabanına aşinayım.