Bu sayfada, Google Season of Docs için kabul edilen bir teknik doküman yazma projesinin ayrıntıları yer almaktadır.
Proje özeti
- Açık kaynak kuruluşu:
- The Linux Foundation
- Teknik yazar:
- boron
- Proje adı:
- Doküman barındırma ve oluşturma işlemlerini yeniden düzenleyin, başlangıç sayfalarını ve geliştirici kılavuzlarını yeniden yapılandırın.
- Proje uzunluğu:
- Standart süre (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 tasarlanır. İyi bir dokümantasyon, kullanıcıların bir yazılımı nasıl kullanacaklarını, özelliklerini, ipuçlarını 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. Ayrıca destek maliyetini düşürür ve ürünün kurumsal ve açık kaynak kimliğinin bir parçasıdır : İyi bir dokümantasyon, ürünün ve geliştirici ekibinin sağlıklı olduğunun bir işaretidir.
İyi bir dokümantasyon olmadan kullanıcılar yukarıdaki işlemleri etkili ve verimli bir şekilde nasıl yapacaklarını bilemeyebilir. Mükemmel iletişim her zaman her işletmenin veya ürünün kalbinde yer aldığından ve almaya devam edeceğinden, dokümanlar bir ürünün başarısını sağlamada önemli bir rol oynayabilir. Mükemmel bir doküman, bu iletişimi alıp herkesin başarı için erişebileceği yönetilebilir bir çerçeveye yerleştirir.
Her dokümantasyon sitesinin iyi bir oluşturma ve barındırma iş akışı hattına ihtiyacı vardır. AGL gibi, birden çok sürümün ve çok sayıda ayrıntılı dokümanın bulunduğu bir kuruluşta dokümantasyon dosyaları (Markdown) birden çok depoya yayılır. Bu durum, dosyaların bakımını ve güncellenmesini inanılmaz derecede karmaşık ve zaman alıcı hale getirir.
Mevcut Durum :
- AGL doküman web sitesi, çeşitli depolardan alınan bir grup Markdown dosyasına dayanır.
- Doküman sayfaları şu anda Cordova projesinin motoru kullanılarak Markdown olarak ayrı kaynaklarda barındırılmaktadır.
- Bu durum, doküman oluşturma ve barındırma süreci için dört depolu bir kuruluma yol açar :
- 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 otomatik olarak teknik bir web sitesi oluşturmaya yönelik araçlar içerir.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : Genel belgeler ve kılavuzlar için kaynak (markdown'lar [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]).
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : Doküman sitesi [https://gist.github.com/growupboron/docs.automotivelinux.org] için dağıtılan GitHub Pages deposu.
- docs-tools [https://github.com/automotive-grade-linux/docs-tools] içinde bulunan bir araç (komut dosyası), docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] içinde bulunan fetched_files.yml dosyasına göre tüm Markdown dosyalarını toplar ve şablon haline getirir.
- Agl dokümanları web sitesi oluşturma ile ilgili 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. Ardından, tüm kitap yaml dosyalarını uzak depolardan docs-webtemplate'e [https://github.com/automotive-grade-linux/docs-webtemplate] getirir. Kitap YAML dosyaları, uzak depodaki Markdown dosyalarınızın tüm URL'lerini içerir.
- Tüm Markdown dosyaları getirildikten sonra araçlar, buna uygun şekilde dağıtılan docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] içinde AGL dokümanı web sitesini oluşturmak için işleme başlar.
- Mevcut işlem hattını koruma süreci, özellikle yeni katkıda bulunanlar için kullanıcı ve geliştirici dostu değildir. Bu iş akışı hattı (oluşturma ve barındırma), geliştiricilerin doküman oluşturma ve dağıtım iş akışını sürdürmek yerine doküman oluşturma kısmına odaklanabilmesi için çok daha fazla basitleştirilebilir ve kolaylaştırılabilir.