CERN-HSF projesi

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:
Ariadne
Proje adı:
Rucio – Rucio belgelerini modernize etme (yeniden yapılandırma ve yeniden yazma)
Proje uzunluğu:
Standart uzunluk (3 ay)

Proje açıklaması

Özet: Rucio çerçevesi, heterojen veri merkezleri arasında coğrafi olarak farklı konumlara dağılmış büyük miktarlarda bilimsel veriyi yönetip düzenlemek amacıyla geliştirilmiştir. Dağıtılmış veri kurtarma ve uyarlanabilir çoğaltma gibi özellikler sunan bu çerçeve, son derece ölçeklenebilir, modüler ve genişletilebilirdir. Bu tür bir hizmetin dokümanlarını kullananlar farklı geçmişlere sahip olur ve dokümanlara erişirken farklı gereksinimlere sahiptir. Bu nedenle, bu tür bir hizmetin iyi dokümante edilmesi, son kullanıcılar için hizmetin benimsenmesini ve kullanımını kolaylaştırırken yaygın sorunlar ve sorun giderme için de referans görevi görmelidir.

Bu tür dokümanlar olmadan verimli ve etkili bir şekilde kullanımda önemli engeller yaşanır. Bu durum, destek maliyetlerinin artmasına neden olabilir ve ürünün kurumsal kimliği için itibar riski oluşturabilir. Belgeleme de bir iletişim şeklidir. Bu nedenle, iletişimin uygun sürümlemeyle alakalı kalırken yönetilebilir ve erişilebilir bir çerçeveye yerleştirilmesini sağlamak, başarılı bir iletişim kurmamızı sağlar.

Bu makalenin yazıldığı sırada Rucio çerçevesi, LHC'deki ATLAS ve CMS deneylerinin yüksek enerji gereksinimlerini karşılamak için kullanılıyordu. Ayrıca LHC'nin dışında astrofizik gibi çeşitli bilimsel toplulukların ihtiyaçlarını desteklemek için de kullanılmaktadır. Bu nedenle, belgelerin mümkün olduğunca alakalı ve erişilebilir olması gerekli hale gelir. CERN, bu projenin yardımıyla Rucio'nun son kullanıcılarının, ilgili tüm dokümanlara erişmek için merkezi bir görünüm sağlayarak çerçeveyi kullanırken sorunsuz bir deneyim yaşamasını sağlamak istiyor.

Mevcut Durum: Bugünden itibaren kullanıcı dokümanları farklı yerlere dağıtılmıştır ve bunlar arasında bilimsel makaleler, kaynak kodla Readthedocs.io, Google Drive, GitHub, DockerHub veya Wikis gibi birden çok biçimde sunulmaktadır. Birden fazla kaynak, sürümlerin takibi ve dokümanların doğruluğuyla ilgili sorunlara yol açar. Ayrıca, merkezi olmayan bir belgeleme modeli, belirli bir kullanım alanı için alakalı bilgilerin gösterilmesi ve gösterilmesi konusunda önemli engeller oluşturmaktadır. Özellikle Wiki'lerde, belirli bir deneme için sağlanan bilgiler aynı/diğer kaynaklarda bulunan diğer örnekler için de geçerli olabilir. Ancak birleştirilme ve uygun bağlantılar eksikliği nedeniyle bu bilgiler kullanılmaz durumda ve muhtemelen yeterince kullanılmamaktadır.

Önerdiğiniz kullanıcı dokümanları neden mevcut dokümanlara göre daha iyi? Çok yönlü sorun göz önünde bulundurulduğunda, aşağıda önerilen model aşağıda ayrıntılı olarak anlatıldığı gibi gezinme, sürüm oluşturma, izleme ve belgelemeyle ilgili engelleri ortadan kaldırır:

Belgelerin yeniden yapılandırılması, son kullanıcı için gezinmenin sarf ettiği çabayı kolaylaştırmayı amaçlar. Bilgi ararken alakasız sayfalara bakmak zorunda kalmaz. Yeniden yapılanma, gerekliliğe göre kategori oluşturma özgürlüğü sunacağından yönetim açısından sürüm oluşturma ve izleme kolaylaştırılır. Yeniden yapılandırılmış dokümanların tümünü merkezileştirmek, tüm bilgilerin birden fazla kaynağa başvurmak zorunda kalmadan kullanıcı tarafından görülebilmesini sağlar.

Analiz: Şartlar özetini okuyup danışmanlık ekibiyle görüştükten sonra, Rucio dokümanlarının mevcut durumuyla ilgili çıkardığım sonuçlar aşağıda verilmiştir:

Altı ana doküman kaynağı vardır: - Google Drive Bağlantısı : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7

  • Kaynağı Sphinx tarafından desteklenen ve kodunda kaynak bulunan Readthedocs Kod Bağlantısı: https://github.com/rucio/rucio Readthe Docs bağlantısı: https://rucio.readthedocs.io/en/ araçları

  • DockerHub Bağlantı: https://hub.docker.com/u/rucio

  • GitHub Bağlantısı: https://github.com/rucio/rucio

  • Wikiler Bağlantı: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing

  • Bilimsel Makaleler Bağlantı: https://arxiv.org/abs/1902.09857

Bu kaynaklardaki dokümanlar farklı biçimlerdedir. Örneğin, Google Drive'da Slaytlar ve Dokümanlar biçiminde dokümanlar, GitHub'da ise temel olarak reStructuredText işaretleme dilinde dosyalar bulunur. Sürüm ve izleme eksikliği, birden fazla kaynakta gereksiz bilgilerin yayınlanmasına neden olur. Bilgilerin etiketlenmesinde/sınıflandırılmasında tutarlılık yoktur. Bu nedenle, arama yaparken önceki deneyim ve uzmanlık gerekir.

Çok sayıda biçim ve kaynak göz önünde bulundurulduğunda, bilgilerin yeniden yapılandırılması ve mkdocs kullanılarak merkezileştirilmesi bekleniyor. Araçlar hakkında daha fazla bilgi edinmek için araştırma yaptım ve kullanımlarını öğrendim.

Sonuç: Mevcut dokümanlar yapılandırılmamış ve uygun bağlantılar olmadan dağınık. Ayrıca, biçimlendirmede merkezileşme ve tekdüzelikten yoksundur. Bu da kullanıcıların aramalar için daha fazla çaba göstermesine neden olur. Bu tür boşluklar, yöneticiler/bakım uzmanları/yöneticiler üzerinde gereksiz baskı oluşturur. Bu da dokümanların bakımı ve güncellenmesi için topluluk odaklı bir yaklaşım sürdürmeyi zorlaştırır. Kullanıcı ve katkıda bulunanların deneyimi önemli ölçüde bozulur ve tekrarlanan

Önerilen dokümanların yapısı: Şartları ayrıntılı bir şekilde analiz ettikten sonra, yeniden yapılandırılmış bir doküman modeli aracılığıyla en önemli sorunları ele almaya karar verdim.
Yeniden yapılandırılmış model, aşağıda ekli taslakta gösterilmektedir ve her dokümanı aşağıdaki 7 kategoriye ayırır:

  • Hakkında
  • Başlarken
  • Kavramlar
  • Rucio Arayüzleri
  • Görevler
  • Eğiticiler
  • İleri düzey bilgi

Elbette, bu programın tamamlanmasının ardından üzerinde çalışmak istediğim bağlantı ekleme gibi iyileştirmeler var. Rucio'da 500 petabayt veriye erişen 1.000'den fazla etkin kullanıcıyla, dokümanlarında önerilen yeniden yapılanma, kullanıcıların destek posta listesine başvurma ihtiyacını önemli ölçüde azaltabilir. Hedef, tıklama oranlarını düşürerek ve belgeleri kategorilere ayırıp etiketleyerek kullanıcı deneyimini iyileştirmektir. Kullanıcı/operasyon/yönetici personeli açısından bilinmesi gereken her şey 3 tıklama veya daha kısa sürede bulunabilir.

Maket bağlantısı: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

Proje Hedefleri: - Çeşitli kaynaklardan elde edilen gereksiz bilgileri analiz edin ve kaldırın. Yani her bilginin tek bir doğru kaynağı olmalıdır. - Mevcut dokümanları etiketleyip farklı bölümlere ayırarak yeniden yapılandırın - Yeniden yapılandırılmış dokümanları mkdocs'a dayalı merkezi bir görünüme taşıyın - Dosya biçimi kısıtlamaları nedeniyle taşınamayan dokümanları yeniden biçimlendirin/içe aktarın - Bağlantılar, bilgilerde yapılan güncellemeler veya hataların düzeltilmesi açısından eksikliklerin giderilmesini sağlamak için dokümanların topluluk tarafından değiştirilmesini ayarlayın.

Bu sistemin temelleri zaten mevcuttur. Ancak benim modelim, uygun dokümanlar ile katkı ve yönetim için uygun yönergeler belirleyerek mevcut sistemi iyileştirir. Ayrıca, sorunları ve projenin genel durumunu izlemek için GitHub proje panolarını da dahil etmeyi planlıyorum.

Zaman çizelgesi: - 16 Ağustos'tan önce --> Dokümanların güncel sürümleri ve Rucio hakkında bilgi sahibi olun --> Proje süresince faydalı olacak yeni teknikleri ve teknik yazma becerilerini edinin --> GitHub'da bildirilen belgelerle ilgili sorunlara (varsa) katkıda bulunun

  • Toplulukla bağ kurma (17 Ağustos - 13 Eylül) --> Saat dilimlerindeki farkı hesaba katmak için bir iletişim kanalı ve zaman ayarlayın (Pune 3 saat 30 dakika ileridedir) --> Hedeflerin hassaslaştırılması için tespit edilecek önemli sorunlar --> Sohbetlere katılarak topluluk, kuruluş ve çerçeve hakkında daha fazla bilgi edinin. --> Önerilen doküman yapısının uygulanabilirliği ve uygulanabilirliği için mentorlar ve kuruluşun diğer önemli üyeleriyle birlikte değerlendirilmesi. --> Önerilen özelliklerin ve mevcut dokümanlarda yapılması gerekebilecek diğer değişikliklerin tamamlanması.

  • Belgelendirme Dönemi (14 Eylül - 30 Kasım) Belirlediğim formata göre, belgelendirme döneminde ulaşmak istediğim önemli aşamaların dökümünü aşağıda bulabilirsiniz.

--> 1. Dönüm Noktası: Kategorize Etme ve Etiketleme ETC: 28 Eylül 2020 Mevcut dokümanları bir araya getirmek ve etiketlemek, yeniden yapılanma ve budama sürecini büyük ölçüde basitleştirecektir.

--> 2. Ara Hedef: Analiz, Budama ve Yeniden Yapılandırma VK: 19 Ekim 2020 1. Ara Hedef sırasında sınıflandırılan belgeler, yineleme ve gereksiz bilgi kaynaklarını bulmak için analiz edilir. Proje bilgilerinde belirtildiği gibi, elimizdeki tüm bilgiler için tek ve doğru bir kaynağı hedefliyoruz.

--> 3. Ara Hedef: Merkezileştirme ve Yeniden Biçimlendirme: ETC: 9 Kasım 2020 Belgeler uygun şekilde kısaltılıp yeniden yapılandırıldıktan sonra öncelikle belgeyi yeniden biçimlendirmeyi hedefliyorum. Çeşitli kaynaklar nedeniyle, biçimler farklıdır ve öncelikle uygun bir biçime dönüştürülmeleri gerekir. Bu tamamlandıktan sonra merkezileştirme süreci kolaylaşacak.

--> 4. Dönem: İzleme panoları oluşturma + yönetim/katkılarla ilgili dokümanlar ETC: 23 Kasım 2020 Bu aşama, projenin tamamlanmasından sonra dokümanların güncel kalmasını sağlamak içindir. Yönergeler belirlemek ve proje panoları oluşturmak, yönetim üyelerinin topluluktan katkı isteme ve bunları etkili bir şekilde izleme yükünü hafifletir.

--> Proje Değerlendirmesi (30 Kasım - 5 Aralık) Proje raporu ve mentorlarımın değerlendirmesini gönderme Docs Sezonu katılımcısı olarak yaşadığım deneyimle ilgili bir rapor yazıp gönderme.

Neden bu proje? Kodu iyi yazılmış ve sürümlendirilmiş belgelerle desteklemenin, daha fazla benimsenmesini ve daha iyi kullanımını sağlamanın tek yolu olduğuna inanıyorum. Şahsen, CERN'in fiziğin farklı alanlarında son teknoloji araştırmaların öncüsü olması beni büyülüyor. Bu tür denemeler sırasında işlenen, aktarılan ve oluşturulan bilgilerin ölçeği göz önüne alındığında, kuruluş içinde referans ve gelecekteki kullanım için verilerin nasıl yönetildiğine dair her zaman merak duyuyordum. Muhteşem bilimsel araştırmalara ve keşiflere güç veren bir çerçevenin dokümanlarının iyileştirilmesine katkıda bulunmak benim için bir onur olacaktır.

Bu proje için neden doğru kişi benim? Ön koşulları karşılamanın yanı sıra, aşağıdaki nedenlerden dolayı bu proje için doğru kişi olacağımdan eminim:

Kubernetes için mevcut belgeleri değiştirmek üzere çalışmaya devam ediyorum. Bu katkılar, 1.19 Kubernetes sürüm döngüsü için Sürüm Dokümanları Gölge Ekibi'ne katılmama neden oldu. Bu ekipte, sürümler sırasında eklenen yeni özelliklerin dokümanlarını etkili bir şekilde sürdürmeye ve yükseltmeye katkıda bulunuyorum. İyi dokümanların mükemmel bir ürün/hizmetin temelini oluşturduğunu düşünüyorum. Prosedürel veya teknik olsun, iyi yazılmış, kısa ve kolay erişilebilir bilgiler, özelliğin benimsenmesini ve daha iyi kullanımını teşvik eder. Kariyerim boyunca veri odaklı dağıtık sistemlerle çalıştığım için bu tür sistemlerin dokümantasyonuyla ilgili şartlardaki incelikleri anlamak için en uygun kişi olduğumu düşünüyorum. Kendim de son kullanıcı olduğum için kötü yazılmış/yanlış dokümanların neden olabileceği sorunlardan haberdar olduğumu ve yeniden yapılanma sırasında bunları dikkate alacağımı belirtmek isterim.