GenPipes 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:
GenPipes
Teknik yazar:
shaloo
Proje adı:
"Read The Docs" sitesinde GenPipes dokümanlarını ayarlama
Proje süresi:
Standart uzunluk (3 ay)

Proje açıklaması

GenPipes dokümanlarını "Read The Docs" üzerinde oluşturma hedefine ulaşmak için 3 adımlı bir plan öneriyorum.

1. adım: PoC

  • Yeni bir kullanıcı / araştırmacı olarak GenPipes'in mevcut dokümanlarını inceleme

    • Eksik bilgileri ve yanlışlıkları tespit edin
    • Yeni doküman konuları önerin (gerekirse)
    • Hedef kitleye hitap etmek için yeni kullanıcılara odaklanan bir bilgi mimarisi haritası taslağı oluşturun.

    (Not: Bu adımda, RTD için GenPipes dokümanlarının barındırılabileceği yeni bir GitHub deposu kurulumu konusunda GenPipes mentorlarından da bilgi almamız gerekebilir. Bu GitHub deposu, RTD derleme ardışık düzenlerindeki tüm dokümanları içe aktarmak için kullanılabilir. Uyulması gerekiyorsa GenPipes depo kuralları ve belge kaynağı yönetim yönergeleri hakkında bilgi edinmeniz gerekebilir. Aksi takdirde, standart olanlar kullanılabilir. Ayrıca PoC için GitHub hesabımı kullanarak örnek bir RTD deposu kurulumunun demosunu yapabilirim (ör.https://gpdocs.readthedocs.io/en/latest/ bu teklif için oluşturduğum örnek budur).

  • Önceki adımdaki inceleme ve analize dayanarak, önerilen GenPipes doküman yapısının / dizinin temel iskeletini oluşturun ve RTD sitesine ekleyin

    • Buna GitHub deposu oluşturma (ör. Sphinx araçlarıyla) ve temel dokümanlar dosyaları dahildir.
    • Bu, çeşitli bölümler / bilgi akışları için hem yeni hem de deneyimli kullanıcıları göz önünde bulunduran yeni bir içindekiler listesi oluşturmayı da içerir.

  • Temel içerik iskeleti içindeki içindekiler bölümünü inceleyin / onay alın

    GenPipes GSoD değerlendirme aşamasında, RTD'de barındırılan bu örnek aracılığıyla GenPipes için değer oluşturmaya çalıştım. Bunun yalnızca demo amaçlı olduğunu, henüz RTD'de herkese açık olarak listelenmeyen korumalı bir bağlantı olduğunu lütfen unutmayın. Kısa listeye alınıp alınmadığımdan bağımsız olarak bu demo, GenPipes RTD çalışmasına hızlı bir başlangıç yapmak için kullanılabilir. c3g/GenPipes GitHub deposundaki kaynakları zaten kontrol ettim. Daha önce Skype'ta yaptığımız "ekran paylaşımı" görüşmesinde mentorlarımız Rola ve Hector bu videodan hoşlanmıştı. Bu nedenle, GSoD Gods'ın da bu videoyu görmek isteyebileceğini düşündüm. Şu anda temel iskeleti hazır ancak zaman uygun olduğunda 30 Temmuz'a kadar güncellemeyi planlıyorum.

https://genpipes.readthedocs.io/en/latest/

2. Adım: GenPipes Dokümanı v0.9 doküman oluşturma

  • GSoD zaman çizelgelerini göz önünde bulundurarak, RTD'de barındırılmak üzere hangi mevcut veya yeni GenPipes dokümanlarının içe aktarılabileceğini, bağlanabileceğini ya da Sphinx/rst tabanlı dokümanlara dönüştürülebileceğini belirleyin.

  • Tanımlanmış dokümanları rst biçimine dönüştürün, gerekirse uygun olduğu yerlerde yeni dokümanlar oluşturun, mümkün olan / ilgili olanları yeniden kullanın.

    • Bu ilk doküman grubunu, kavram kanıtı olarak ReadTheDocs'a aktarın ve korunan bir depo olarak barındırın. İnceleme/resmi geçiş işlemine izin verilene kadar yeni kullanıcıların GenPipes'in orijinal dokümanlarına gitmesini öneren bir not ekleyin.

  • İnceleme/kurs düzeltme/güncelleme

3. Adım: RTD'de ilk taslağı hassaslaştırın, inceleyin ve yayınlayın

  • Önerilen GenPipes yeni doküman yapısının ayrıntılarını GenPipes içindeki İçindekiler bölümünde doldurun. İlk birkaç dokümanın (GenPipes Readme) yanı sıra Kavramlar, Eğitimler vb. ek dokümanlar ekleyin.

  • Yeni kullanıcılar, deneyimli GenPipes kullanıcıları, GenPipes geliştiricileri vb. için İçindekiler bölümünde net bir ayrım yapın.

  • GenPipes doküman grubunun nasıl sürdürülebileceği, kullanıcılar tarafından nasıl düzenlenebileceği ve C3G'nin harici doküman katkıda bulunanlara buna izin verip vermeyeceği konusunda RTD (sphinx derlemeleri) aracılığıyla kısmi otomasyon içeren bir çalışma süreci önerin ve tartışın. Bu işlem, kodlama yönergelerine benzer şekilde doküman güncellemeleri için bazı yönergeler oluşturmayı gerektirebilir. Daha fazla alt adım gerektirebilir. Örneğin, GenPipes dokümanlarındaki yazım denetimini PR onayı öncesinde otomatikleştirin.

Bildir

Son olarak, deneyimlere, günlüklere ve mentorlardan gelen geri bildirimlere dayalı olarak GSoD için bir rapor oluşturun.

Diğer düşünceler

Gelecekte (3 aydan sonra), uygunsa GenPipes için bunu daha uzun süre boyunca sürdürmenize yardımcı olabilirim. Gerekirse başkalarını da aynı konuda eğitebilirsiniz. Bu sorunun cevabını ilk 3 ayın sonucuna göre belirleyebiliriz.

Ayrıca, ek bir proje önerisi fikri öneriyorum: GenPipes için kolay ilk katılıma yardımcı olacak 3 sayfalık bir özet oluşturma. Bugün, dokümanlar iyi ancak dağınık ve yeni kullanıcılara uygun olmadığından yeni bir kullanıcının GenPipes'i kullanmaya başlamadan önce birçok engeli aşması gerekiyor. Bunun 3 ay içinde yapılıp yapılamayacağını bilmiyorum ancak denemek isterim.

Aynı teklifi ve nasıl ortaya çıktığını (geçmiş) https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing adresinden de görüntüleyebilirsiniz.