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:
- Linux Foundation
- Teknik yazar:
- bor
- Projenin adı:
- Belge barındırma, oluşturma ve başlangıç sayfaları ile 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 kullanmalarına yardımcı olmak için tasarlanmıştır. İyi belgeleme, kullanıcılara bir yazılımı, özelliklerini, ipuçlarını ve püf noktalarını öğrenmeleri ve yazılımı kullanırken karşılaşılan yaygın sorunları çözmeleri için bir yol sağladığından ç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 bir göstergesidir.
Kullanıcı, iyi bir belge olmadan yukarıdakilerin nasıl etkili ve verimli bir şekilde yapılacağını bilemeyebilir. Belgeler ü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 bu şekilde olmaya devam edecektir. Mükemmel bir belgeleme ise bu iletişimi alır ve herkesin başarıya ulaşmak için erişebileceği yönetilebilir bir çerçeveye sokar.
Her belgeleme sitesinin iyi bir derleme ve barındırma iş akışı ardışık düzeni olmalıdır. AGL gibi bir kuruluşta, birden çok sürümü ve çok sayıda açıklayıcı belgeye sahip olması, belge dosyaları (işaretlemeler) birden çok depoya dağılmış durumdadır. Bu da dosyaları koruma ve güncelleme görevini son derece karmaşık ve zaman alıcı hale getirir.
Mevcut Durum :
- AGL belgesi web sitesi, çeşitli depolardan getirilen Markdown dosyaları koleksiyonuna dayanır.
- Doküman sayfaları şu anda cordova projesinin motoru kullanılarak Markdown olarak bağımsız kaynaklarda barındırılmaktadır.
- Bu, belge oluşturma ve barındırma işlemi için dört adet depo kurulumuna olanak tanır :
- Docs-webtemplate [https://github.com/automotive-grad-linux/docs-webtemplate] : Jekyll web sitesi şablonunu içerir.
- Dokümanlar araçları [https://github.com/automotive-grad-linux/docs-tools] : Markdown dosyalarından otomatik olarak teknik bir web sitesi oluşturmak için araçlar içerir.
- Docs-sources [https://github.com/automotive-grad-linux/docs-sources] : Genel dokümanlar ve kılavuzlar için kaynak (markdowns [https://github.com/automotive-grad-linux/docs-sources/tree/master/docs]).
- Docs-gh-pages [https://github.com/automotive-grad-linux/docs-gh-pages] : Belge sitesi [https://gist.github.com/growupboron/docs.automotivelinux.org] için dağıtılan GitHub sayfaları deposu.
- Dokümanlar-araçlarında [https://github.com/automotive-Grade-linux/docs-tools] bulunan bir araç (komut dosyası), tüm markdown dosyalarının docs-webtemplate [https://github.com/automotive-Grade-linux/docs-webtemplate] özelliğinde bulunan fetched_files.yml dosyasına göre toplanması ve şablonlanması işlemini gerçekleştirir.
- agl dokümanları web sitesi oluşturmanın geçerli 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. Ardından, tüm kitap yaml dosyalarını uzak depolardan docs-webtemplate [https://github.com/automotive-grad-linux/docs-webtemplate] uygulamasına getirir. Kitap yaml dosyaları, uzak depodaki markdown dosyalarınızın tüm URL'sini içerir.
- Tüm Markdown dosyaları getirildikten sonra, AGL belgesi web sitesini, karşılık olarak dağıtılan docs-gh-pages [https://github.com/automotive-grad-linux/docs-gh-pages] içinde oluşturmak için araçlar işlemi yapılır.
- Mevcut satış hattını koruma süreci, özellikle yeni katkıda bulunanlar için kullanıcı ve geliştiriciler için uygun değil. Bu iş akışı ardışık düzeni (derleme ve barındırma), geliştiricilerin belge oluşturma ve dağıtım iş akışını sürdürmek yerine belgeleme bölümüne odaklanması için çok daha basit ve basit hale getirilebilir.