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:
- The Linux Foundation
- Teknik yazar:
- boron
- Projenin adı:
- Belge barındırma ve oluşturma sürecini yeniden ele alıp başlangıç sayfalarını ve geliştirici kılavuzlarını yeniden yapılandırın.
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Özet :
Dokümanlar, son kullanıcıların ve geliştiricilerin bir ürünü veya hizmeti kullanmasına yardımcı olmak için tasarlanmıştır. İyi dokümanlar, kullanıcıların bir yazılımı nasıl kullanacağını, özelliklerini, ipuçlarını ve püf noktalarını öğrenmelerine ve yazılım kullanılırken karşılaşılan yaygın sorunları çözmelerine olanak tanıdığı için çok önemlidir. Aynı zamanda destek maliyetini de azaltır ve ürünün kurumsal ve açık kaynak kimliğinin bir parçasıdır. İyi bir belgeleme, ürünün ve geliştirici ekibinin sağlıklı olduğunun işaretidir.
İyi bir dokümantasyon olmadan kullanıcılar yukarıdaki işlemleri etkili ve verimli bir şekilde nasıl yapacaklarını bilemez. Belgeler, bir ürünün başarısında çok önemli bir rol oynayabilir çünkü mükemmel iletişim her zaman bir işletmenin veya ürünün merkezinde yer alır ve öyle olmaya devam eder. Mükemmel bir belgeleme de bu iletişimi alır ve herkesin başarıya ulaşmak için erişebileceği, yönetilebilir bir çerçeveye koyar.
Her doküman sitesi için iyi bir oluşturma ve barındırma iş akışı ardışık düzeni gerekir. AGL gibi birden fazla sürüm ve çok sayıda ayrıntılı doküman içeren bir kuruluşta, doküman dosyaları (markdown'lar) birden fazla depoya dağıtılır. Bu da dokümanları koruma ve güncelleme görevini inanılmaz derecede karmaşık ve zaman alıcı hale getirir.
Mevcut Durum :
- AGL doküman web sitesi, çeşitli depolardan alınan markdown dosyalarından oluşan bir koleksiyona dayanır.
- Doküman sayfaları şu anda cordova projesinin motoru kullanılarak Markdown olarak bağımsız kaynaklar içinde barındırılmaktadır.
- Bunun sonucunda, belge oluşturma ve barındırma süreci için dört depo kurulumu oluşturulur :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : Jekyll web sitesi şablonunu içerir.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : Markdown dosyalarından teknik bir web sitesi otomatik olarak oluşturmaya yönelik araçlar içerir.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : Genel dokümanlar ve kılavuzlar için kaynak (markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]).
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : Dokümanlar sitesi [https://gist.github.com/growupboron/docs.automotivelinux.org] için dağıtılmış GitHub Pages deposu.
- docs-tools [https://github.com/automotive-grade-linux/docs-tools] adresinde bulunan bir araç (komut dosyası), tüm Markdown dosyalarını toplamak ve docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] adresindeki fetched_files.yml dosyasına göre şablon haline getirmekten sorumludur.
- agl doküman web sitesi oluşturma işleminin mevcut iş akışı : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- section_version.yml, tüm kitap yaml dosyalarının bağlantılarını içerir. Ayrıca, tüm kitap yaml dosyalarını uzak depolardan docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] hizmetine getirir. Kitap yaml dosyaları, uzak depodaki Markdown dosyalarınızın tüm URL'sini içerir.
- Tüm markdown dosyaları getirilir getirilmez araçlar, docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] adresinde AGL doküman web sitesini oluşturma işlemini başlatır ve bu web sitesi uygun şekilde dağıtılır.
- Mevcut ardışık düzeni sürdürme süreci, özellikle yeni katkıda bulunanlar için kullanıcı ve geliştirici dostu değildir. Geliştiricilerin doküman oluşturma ve dağıtım iş akışını sürdürmek yerine dokümanlara odaklanabilmesi için bu iş akışı ardışık düzeni (oluşturma ve barındırma) çok daha basitleştirilebilir ve kolaylaştırılabilir.