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:
- CERN-HSF
- Teknik yazar:
- SabitaR
- Projenin adı:
- Allpix Squared Dokümanlarının Yeniden Yapılandırılması ve Basitleştirilmesi
- Proje uzunluğu:
- Standart uzunluk (3 ay)
Proje açıklaması
GENEL BAKIŞ CERN-HSF'nin Allpix Squared projesini iki temel nedenden dolayı seçtim:
Beceri geliştirme: Bu projenin mevcut dokümanları kapsamlı ve birden fazla içerik formatını entegre ediyor. Bu kapsamlı doküman paketini denetlemek ve yeniden yapılandırmak, bilgi mimarimi ve yazma becerilerimi geliştirmeme yardımcı olacak. Ayrıca proje alanı (parçacık fiziği) benim için yeni bir alan. Geliştiricilerle etkileşim becerilerimi geliştirmemi sağlıyor. Gerekli ön araştırmayı yapıp doğru soruları sorduğumuz takdirde teknik yazarların geliştiricilerden gelen bilgileri işleyip her düzeydeki kullanıcı için yararlı içerikler sunabileceğine inanıyorum. Bu proje, bu teoriyi test etmemi sağlayacak.
Teknik bilgi: Bu proje için Hugo gerekir. Hugo, öğrenmek istediğim araçlar listesinin en başında yer alır. LaTeX-Markdown-Hugo-GitLab-CI iş akışını öğrenmek için sabırsızlanıyorum.
Teknik yazar keşif aşamasında proje mentorlarıyla kısa bir süre etkileşime geçtim ve mevcut doküman paketi yapısı hakkında bilgi edindim. Ayrıca, Hugo ve Docsy'yi Windows makinemde doğru şekilde yapılandırmamı test etmek için bir demo web sitesi (https://ap2-demo.netlify.app/) oluşturdum. Web sitesini Netlify'ye dağıtabildim ancak Gitlab Pages'e dağıtamadım. Bu projenin mevcut dağıtım iş akışını sürdürebilmesi için Hugo Docsy temasını Gitlab Pages'a dağıtmanın bir yolunu buluyorum.
BEKLENEN PROJE SONUÇLARI: Belgeler, kod referansı, eğitici içerikler ve haberleri bir araya getiren basit bir proje web sitesi. - Kullanıcılara ve geliştiricilere yönelik içerikleri ayıran ve daha önce eksik olan bilgileri içeren, yeniden yapılandırılmış ve gözden geçirilmiş bir kullanıcı kılavuzu. - Nasıl yapılır dokümanlarına, SSS'lere ve sık karşılaşılan sorunlara ait mevcut örneklerden oluşan bir eğitim akışı.
PROJE ARAÇLARI Allpix Squared'ın mevcut dokümanlarında GitLab ve Gitlab CI'nin yanı sıra LaTeX, Doxygen, pandoc ve Hugo kullanılmaktadır. Proje mentorları ve ben, MathJax eklentileriyle içeriği LaTeX'ten Markdown'a taşıma olasılığı hakkında konuştuk. Başarılı olursam doküman iş akışı Hugo, Markdown, Doxygen, git ve Gitlab CI'yi içerecek. Eğitileri aynı web sitesinde/platformda tutmak için Hugo ve Markdown'ı kullanacağım. Eğitimler için araç olarak Codelab'lerin (ClaaT) kullanılabilirliği hakkında bilgi edinmek istiyorum. Bu Temmuz ayında ClaaT-Hugo iş akışını test etmeyi ve seçilirse mentorlarla tartışmayı umuyorum.
PROJE SÜRESİ Allpix Squared projesini standart üç aylık süre içinde (14 Eylül 2020 - 30 Kasım 2020) tamamlamayı talep ediyorum. Bu süre zarfında projeye haftada yaklaşık 15 saat ayıracağım. Bu saatler, gerektiğinde mentor toplantılarını ve ilgili e-postaları içerir. Topluluk bağlarını kucaklamak ve projeyi bitirmek için GSoD zaman çizelgelerine uyacağım.
PROJE GÖREVLERİ Önerilen güncellemelerimizi mevcut Allpix Squared doküman paketine şu şekilde uygulamayı planlıyoruz: 1. Seçenekleri araştırın, tartışın ve keşfedin (17 Ağustos - 13 Eylül 2020): - Proje şartlarını anlayın - Mevcut dokümanlarda eksik bilgiler varsa bunları belirlemek 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 - İçeriği kullanıcı rolüne göre sınıflandırın - LaTeX dosyalarını Markdown'a dönüştürmenin olası etkilerini kontrol edin - Kaynak depoları birleştirin veya birden çok git deposuyla nasıl çalışacağınızı anlayın - Bonus: Eğiticiler için CLaaT'i test edin - Bonus: Katkıda bulunanların yardımcı olması için hızlı stil kılavuzu/kısa kod referansı oluşturun
İçeriği yeniden yapılandırma, inceleme ve iyileştirme (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ı gidermek için bir tampon hafta içerir.
- Kullanıcı iş akışlarını göz önünde bulundurarak mevcut içeriği ve kullanıcı sınıflandırmalarını inceleyin
- Yeniden yapılandırılmış içerik iş akışını farklı kullanıcılar için özetleme ve test etme
- Eksik içeriği kaynaktan alma ve iyileştirme
- LaTeX dosyalarını Markdown'a dönüştürme
- Kullanıcı kılavuzu ve geliştirici kılavuzu içindekiler bölümünü tamamlayın
- Kullanıcı ve geliştirici kılavuzlarının PDF'lerini oluşturma
- Bonus: Eğitim içeriklerini örnekler ve sorunlardan yararlanarak yapılandırma
- Bonus: Nasıl yapılır örnekleri için bir eğitim iş akışı oluşturun Zaman çizelgesi: 5 hafta (Doküman geliştirme aşaması)
Web sitesini oluşturma (19 Ekim - 30 Kasım 2020): Haftada 1-2 görev, görev başına yaklaşık 5-7 saat. Bu zaman çizelgesi, sorunları gidermek ve nihai çıkışta ince ayar yapmak için bir tampon hafta içerir.
- Yayınlama iş akışını anlama ve test etme
- Hugo ve Docsy'yi kullanarak web sitesi yapısı oluşturma
- Docsy'yi kullanarak mevcut otomatik dağıtımı ve iş akışını nasıl sürdüreceğinizi test edin
- Doxygen'den içerik alma
- LaTex veya Markdown içeriklerinden kullanıcı kılavuzu, geliştirici kılavuzu ve eğitici içerikler geliştirme
- Proje web sitesinin görünümüne ve tarzına son şeklini vermek (logo, renkler, şablon, düzen, bağlantılar, kullanılabilirlik ve Gitlab CI/CD) Zaman çizelgesi: 6 hafta (Doküman geliştirme aşaması)