Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.
Proje özeti
- Açık kaynak kuruluşu:
- gRPC-Gateway
- Teknik yazar:
- iamrajiv
- Proje adı:
- gRPC-Gateway'in Mevcut Dokümanlar Sitesini Yeniden Düzenleme
- Proje uzunluğu:
- Standart uzunluk (3 ay)
Proje açıklaması
ÖZET:
Kullanıcı doküman sitesi, son kullanıcıların bir ürünü veya hizmeti kullanmasına yardımcı olmak için tasarlanmıştır. Kullanıcı dokümanlarının bulunduğu iyi bir site, kullanıcıların yazılımı nasıl kullanacaklarını, özelliklerini, ipuçları ve püf noktalarını öğrenmelerine ve yazılımı kullanırken karşılaşılan yaygın sorunları çözmelerine olanak tanıdığı için çok önemlidir. Destek maliyetini de azaltır ve ürünün kurumsal kimliğinin bir parçasıdır. Kullanıcı dokümanları sitesinin iyi olması ürünün, yani geliştirici ekibinin sağlıklı olduğunun göstergesidir. İyi bir kullanıcı dokümanı sitesi olmadan kullanıcılar yukarıdaki işlemleri etkili ve verimli bir şekilde nasıl yapacaklarını bilemeyebilir. Kullanıcı dokümanı sitesi, bir ürünün başarısında önemli bir rol oynayabilir. Bunun nedeni, mükemmel iletişimin her işletmenin veya ürünün merkezinde yer alması ve her zaman da öyle kalmasıdır. Mükemmel dokümanlar ise bu iletişimi alıp herkesin başarıya ulaşmak için erişebileceği yönetilebilir bir çerçeveye yerleştirir.
Bu makalenin yazıldığı sırada gRPC-Gateway deposu yaklaşık 1.200 kez çatallandı ve 184 kişi bu depoya katkıda bulundu. Bu, dünyanın dört bir yanındaki birçok kişinin gRPC-Gateway'i kullandığını ve gRPC-Gateway'in nasıl kullanılacağı konusunda rehberlik 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 güncel değil ve eksik. gRPC-Gateway topluluğu, mevcut dokümanlar sitesini yeniden yapılandırmak ve son kullanıcıların gRPC-Gateway'ı kullanırken sorunsuz bir deneyim yaşamasını sağlamak için bu projeyi kullanmak istiyor.
MEVCUT DURUM:
Şu anda gRPC-Gateway dokümanlar sitesinde iki önemli sorun var:
• İlk sorun, kötü ve güncel olmayan dokümanlar web sitesidir. Yani sitenin stili ve yapısı, kullanılan tema eski, eksik, gezinmesi veya bilgi bulmak zor, iyi dokümanlar web sitesinin birçok özelliğini kapsamıyor. gRPC-Gateway'ın mevcut Dokümanlar sitesini yeniden yapılandırırken web sitesinin stilini belirleme, doküman arama gibi özellikler ekleme, web sitesinin kullanıcı arayüzünü iyileştirme, eğitici içerikleri ve örnekleri uygun bir kenar çubuğunda düzenleme ve yeni bir akış şeması tasarlayarak mevcut akış şemalarını ve resimleri güncelleme gibi işlemleri yapacağım. Birincil hedefim bu olacak ve işim daha çok mevcut Dokümanlar sitesinin stilini belirleme ve yeniden yapılandırmaya odaklanacak.
• İkinci sorun, gRPC-Gateway'ın mevcut dokümanlarını, eğitimlerini ve örneklerini yeniden düzenleme ihtiyacıdır. Bu, dosyalardaki yazım ve dil bilgisi hatalarını kaldırarak, Go snippet'lerini doğru şekilde hizalayarak ve Go snippet'lerini Gofmt biçimlerine göre yeniden düzenleyerek yapılabilir. Ayrıca, gerekirse daha fazla doküman, eğitim ve örnek ekleyebiliriz veya mevcut dosyaları yeniden düzenledikten sonra yeniden kullanabiliriz. Bu, ikincil hedefim. Birincil hedefimi (mevcut Dokümanlar sitesini biçimlendirme ve yeniden yapılandırma) tamamladıktan sonra bu işlemi yapacağım.
ÖNERİLEN DOKÜMANLAR SİTESİ NEDEN MEVCUT DOKÜMANIN ÜZERİNDE BİR İYİLEŞTİRME OLDUĞUNU SÖYLÜYOR?
Önerilen kullanıcı dokümanı web sitesi, son kullanıcının verimliliğini, tutarlılığını ve rahatlığını iyileştirmek ve sağlamak için yapılandırılacak. İyi stilize edilmiş bölümler ve yazılı kılavuzların yanı sıra ilişkili akış şemaları ve resimler içeren özelliklerle daha iyi bir görünüm ve kullanıcı arayüzü elde edersiniz.
gRPC-Gateway belgelerinde yöntem ve örneğin iyi bir açıklaması yer alır. Ancak hâlâ eski Jekyll temasını kullanıyor. Günümüzde daha iyi SSG (Statik Site Oluşturucu) Jekyll temalarımız var. Ayrıca, sayfaların yeniden yapılandırılması ve yeni örnekler ve eğitici içerikler ekleyerek, önceki içerikleri güncelleyip yeniden yazarak kullanıcılar için daha yararlı hale getirilmesi gerekiyor.
ÖNERİLECEK HEDEF VE FİKİRLERİN YAPISI VE YOL HARİTASI:
BU PROJENİN BİRİNCİL HEDEFİ:-
Yukarıdaki hedefler ve fikirler aşağıdaki şekillerde uygulanabilir:
Mevcut Jekyll temasını daha iyi ve güçlü bir temaya geçirme. Jekyll temalarının tekrar kullanılmasının nedeni, yeni Jekyll temasına benzer mevcut Jekyll çerçevesini ve temasını zaten bildikleri için, koruyucuların projeye katkıda bulunmalarının ve projenin iş akışını anlamalarının kolay olmasıdır.
İnternetteki farklı Jekyll temalarını inceledikten sonra, aşağıdaki özellikten dolayı https://idratherbewriter.com/documentation-theme-jekyll/ temalar paketinin gRPC-Gateway dokümanları için en uygun olduğunu düşünüyorum:
• Markdown:- Böylece teknik yazarların yükleme konusunda endişe duymaları gerekmez. Kullanıcılar .md dosyasına doğrudan yazabilir. Herkes web sitesinde gösterilen düzenle düğmesini tıklayabilir (yeni özellik) ve sayfayı daha iyi hale getirmek için katkıda bulunabilir (GitHub'da sayfayla ilgili değişiklikleri düzenleyebilir/önerir). Bu sayede kullanıcılar yeni içerik eklemeye veya mevcut içeriği iyileştirecek şekilde düzenlemeye teşvik edilir.
• Doküman Arama:- Kullanıcıları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ılar, yayınlar ve eğitici içeriklerle ilgili görüşlerini paylaşmak için yorum yapabilir. Proje dokümanları hakkında diğer kullanıcıların görüşlerini okuyabilirler.
• Yeni Sürüm Notları ve Bloglar:- Web sitesi, mevcut geliştirme ve yol haritası ile ilgili yeni blog yayınları ve haberlerle güncellenmelidir. Bu nedenle, açılış sayfasında bir tür blog 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 anında yansıtılır. Ayrıca dağıtım ve derleme süreci de kolay olmalıdır. Gelecekte çerçeveyi değiştirmek istersek kullanırız. O zaman kolay olacaktır. Çoğu çerçeve Markdown yazımını destekler. Bu nedenle, .md dosyalarını taşımak ve birkaç değişiklik yapmak 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ında gRPC-Gateway'in temel özellikleri belirtilmelidir.
- gRPC-Gateway'i kullanmaya başlama (kullanıcı rehberine yönlendirme)
- Basit kurulum talimatları (kısa komutlar)
- gRPC-Gateway'i neden kullanmalısınız?
- gRPC-Gateway kullanan proje
Dolayısıyla temel fikir, uzun bir açıklama yazmak yerine açılış sayfasında ana noktaları göstermek ve ayrıntılar için bağlantıyı sağlamaktır.
• gRPC-Gateway Kullanıcı Rehberi 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ı, Belge kurulumu, Geliştirme iş akışı vb. kaynaklar, içindeki benzer sayfaları işaret ediyor. Bu nedenle, tüm dosyaların yeniden düzenlenmesi ve yeniden düzenlenmesi gerekir. Ana Geliştirme sayfası tüm bu sayfaları içermelidir ve köprü her adımda oluşturulur.
• gRPC-Gateway Sayfası Hakkında:
Tüm katkıda bulunanların listesi ekip bölümlerinde yer almalıdır. Kullanıcıların mevcut gRPC-Gateway haberleri hakkında bilgi edinmesini sağlamak için hızlı bağlantılar ve sürüm notları, en son bloglar eklenecektir.
• Bloglar, Sürüm Notları ve Eğitimler Sayfası:-
Web sitesinin bir blog yazma seçeneği olması gerektiğini düşünüyorum. Böylece haberler ve sürümler kolayca paylaşılabilir. Eğitim sayfasında, gRPC-Gateway API'lerini ve kavramlarını açıklayan bazı popüler konuşmalar ve makaleler yer alır. Katkıda bulunanlar, eğitim sayfasına eğitim bağlantılarını ekleyebilir.
Yukarıdaki görevi tamamladıktan sonra, aynı değişiklikleri v2 dalında güncelleyin ve gRPC-Gateway ana dalıyla uyumlu hale getirin.
BU PROJENİN İKİNCİL HEDEFİ:-
gRPC-Gateway dokümanını daha güçlü ve okunaklı hale getirmek için başka değişiklikler yapılması gerekiyor:-
• gRPC-Gateway'ın mevcut tüm dosyalarında dil bilgisi ve yazım hatalarını düzeltme ve sitedeki bağlantı ve yayınları düzenleme ve hizalama.
• Özelliklerin çoğunun AWS, Arka Plan ve Kullanım gibi sitenin Dokümanlar bölümündeki çok kısa dokümanlara sahip olması nedeniyle, gerekirse gRPC-Gateway'e daha fazla doküman ve içerik ekleyin.
• Go snippet'lerini 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 ana dalıyla uyumlu hale getirin.
NEDEN BU PROJE İÇİN DOĞRU KİŞİYİM?
Bu proje için doğru kişi olduğumu düşünüyorum çünkü:
• Geçmişte kurumların belgelerini iyileştirme konusunda deneyime sahibim ve dilediğiniz sürüm kontrol sistemini kullanabilirim. Bu nedenle, GitHub'da komut çalıştırmak sorun olmayacak. • Dahası, insanlara değer katan projelerde çalışmamı sağlıyor. Birinin bir işi mümkün olan en verimli şekilde yapmasını istiyorsanız bunu belgelemeniz gerektiğini düşünüyorum. Süreçlerinizi belgeleyerek, projeye dahil olan herkes için verimlilik, tutarlılık ve içinizin rahat olmasını sağlarsınız. • Son iki aydır gRPC-Gateway\'e katkıda bulunduğum ve 11 PR\'nin birleştirildiği için gRPC-Gateway\'in iş akışı ve kod tabanı hakkında bilgi sahibiyim.