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:
- CERN-HSF
- Teknik yazar:
- SabitaR
- Projenin adı:
- Allpix Kareli Belgelerinin Yeniden Yapılandırılması ve Kullanımı
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
GENEL BAKIŞ CERN-HSF'nin Allpix Squared projesini iki ana nedenden dolayı seçtim:
Beceri kazanma: Bu projenin mevcut belgeleri kapsamlıdır ve birden fazla içerik biçimini entegre etmektedir. Bu kapsamlı belge paketini denetlemek ve yeniden yapılandırmak, bilgi mimarisini ve yazma becerilerimi geliştirmeme yardımcı olacak. Ayrıca, proje alanı (parçacık fiziği!) benim için yeni. Bu yöntem, geliştirici etkileşim becerilerimi geliştirmemi sağlıyor. Gerekli arka plan araştırmalarını yaparsak teknik yazarların geliştiricilerden gelen girdileri işleyebileceklerini ve her seviyedeki kullanıcılara yönelik faydalı içerikler sunabileceklerini düşünüyorum. Bu proje sayesinde bu teoriyi test edebilirim.
Teknik bilgi: Bu proje için Hugo gerekiyor. Hugo, öğrenilecekler listemin en üstünde yer alıyor. LaTeX-Markdown-Hugo-GitLab-CI iş akışını öğrenmek için sabırsızlanıyorum.
Teknik yazar keşfi aşamasında proje danışmanlarıyla kısa bir süre etkileşimde bulundum ve mevcut belge paketi yapısı hakkında bilgi edindim. Hugo ve Docsy'yi Windows makinemde doğru şekilde yapılandırıp yapılandıramayacağımı test etmek için bir demo web sitesi (https://ap2-demo.netlify.app/) oluşturdum. Web sitesini Netlify'a dağıtabildim ancak Gitlab Sayfalarına yerleştiremedim. Bu projenin mevcut dağıtım iş akışını koruması için Hugo Docsy temasını Gitlab Sayfaları'na dağıtmanın bir yolunu bulacağım.
BEKLENEN PROJE SONUÇLARI - Dokümanlar, kod referansı, eğiticiler ve haberleri entegre eden sadeleştirilmiş bir proje web sitesi. - Kullanıcılar ve geliştiriciler için hazırlanan içeriği ayıran, önceden eksik bilgileri içeren, yeniden yapılandırılmış ve gözden geçirilmiş bir kullanıcı kılavuzu. - "Nasıl yapılır?" belgeleri, SSS'ler ve yaygın olarak karşılaşılan sorunlara ilişkin mevcut örneklerden eğiticiler iş akışı.
PROJE ARAÇLARI Allpix Squared'in mevcut belgeleri GitLab ve Gitlab CI'nın yanı sıra LaTeX, Doxygen, pandoc ve Hugo'yu da kullanmaktadır. Proje danışmanlarımız ve ben, MathJax eklentilerini kullanarak LaTeX'teki içerikleri Markdown'a taşıma konusunda görüştük. Başarılı olursam doküman iş akışım Hugo, Markdown, Doxygen, git ve Gitlab CI'yı içerecek. Eğiticileri aynı web sitesi/platform içinde tutmak için Hugo ve Markdown'ı kullanacağım. Eğiticiler için Araç Olarak Codelab'leri (ClaaT) kullanmanın ne kadar uygun olduğunu merak ediyorum. Bu Temmuz ayında ClaaT-Hugo iş akışını test etmeyi ve seçilirse mentorlarla konuşmayı umuyorum.
PROJE SÜRESİ Allpix Squared projesini standart üç aylık dönem (14 Eylül 2020 - 30 Kasım 2020) içinde tamamlamak istiyorum. Bu süre boyunca haftada yaklaşık 15 saat harcayacağım. Bu saatler arasında mentor toplantılarını ve gerektiğinde ilgili e-postaları da içerecektir. Topluluk bağ kurması ve proje kesinleştirmesi için de GSoD zaman çizelgelerine uyacağım.
PROJE GÖREVLERİ Önerdiğim güncellemeleri mevcut Allpix Squared belge paketine şu şekilde uygulamayı planlıyorum: 1. Seçenekleri araştırın, tartışın ve keşfedin (17 Ağustos - 13 Eylül 2020): - Proje gereksinimlerini anlayın - Mevcut dokümanlardaki eksik bilgileri (varsa) tanımlamak için Allpix Squared yazılımını yükleyin. - Gerekli kimlik bilgilerini isteyin. - Allpix Squared'in farklı kullanıcıları için kullanıcı iş akışları oluşturun - İçerikleri kullanıcı rolüne göre sınıflandırın - LaTeX dosyalarını Markdown'a dönüştürmenin sonuçlarını kontrol edin - Kaynak depolarını birleştirin veya birden fazla git deposuyla nasıl çalışacağınızı anlayın - Bonus: Bonus: Eğiticiler için bir seçenek olarak CLaaT'ı test edin - Bonus: Katkıda bulunanlara yardımcı olmak için hızlı bir stil kılavuzu/kısa kod belgeleri hazırlayın:
İçeriği yeniden yapılandırın, gözden geçirin ve iyileştirin (14 Eylül - 19 Ekim 2020): Haftada iki görev, görev başına yaklaşık 5-7 saat. Bu zaman çizelgesi, beklenmedik gecikmeleri veya sorunları ele almak için bir tampon hafta içerir.
- Kullanıcı iş akışlarını göz önünde bulundurarak mevcut içerik ve kullanıcı sınıflandırmalarını inceleyin
- Farklı kullanıcılar için yeniden yapılandırılmış içerik iş akışlarını özetleyip test edin
- Eksik içeriği temin edin ve iyileştirin
- LaTeX dosyalarını Markdown'a dönüştürme
- Kullanıcı rehberi ve geliştirici kılavuzu içindekiler tablosunu sonuçlandırın
- Kullanıcı ve geliştirici kılavuzlarının PDF'lerini oluşturun
- Bonus: Örneklerden ve sorunlardan eğitici içeriklerin içeriklerini yapılandırın
- Bonus: "Nasıl yapılır?" örnekleri için bir eğitim iş akışı oluşturun Zaman çizelgesi: 5 hafta (Belge geliştirme aşaması)
Web sitesini oluşturmak (19 Ekim - 30 Kasım 2020): Haftada 1-2 görev, görev başına yaklaşık 5-7 saat. Bu zaman çizelgesi, sorunların giderilmesi ve nihai çıktıda ince ayar yapılması için bir hafta ara içerir.
- Yayınlama iş akışını anlama ve test etme
- Hugo ve Docsy'yi kullanarak web sitesi yapısı oluşturma
- Dokümanlary'yi kullanarak mevcut otomatik dağıtımı ve iş akışını nasıl sürdüreceğinizi test edin
- Doxygen'den içerik al
- LaTex veya Markdown içeriğinden kullanıcı kılavuzu, geliştirici kılavuzu ve eğitici içerikler geliştirin
- Proje web sitesinin genel görünümünü (logo, renkler, şablon, düzen, bağlantılar, kullanılabilirlik ve Gitlab CI/CD) tamamlayın. Zaman çizelgesi: 6 hafta (Belge geliştirme aşaması)