Bu sayfa, Google Dokümanlar Sezonu için kabul edilen teknik yazı projesinin ayrıntılarını içerir.
Proje özeti
- Açık kaynak kuruluşu:
- GenPipes
- Teknik yazar:
- shaloo
- Proje adı:
- "Belgeleri Okuyun" bölümünde GenPipes dokümanlarını ayarlayın
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
"Belgeleri Okuyun" bölümünde GenPipes dokümanları oluşturma hedefine ulaşmak için 3 adımlı bir plan öneriyorum.
1. Adım: İlgili Kişi
Yeni bir kullanıcı / araştırmacı olarak GenPipes ile ilgili mevcut dokümanları gözden geçirin
- Eksik bilgileri veya yanlışlıkları tanımlayın
- Yeni doküman konuları önerme (gerekirse)
- Yeni kullanıcılara odaklanarak hedef kitleye hitap etmek için bilgi mimarisi haritası taslağı oluşturun.
(Not: Bu adımda, RTD için genpipes belgelerinin barındırılabileceği yeni bir GitHub deposu kurulumuyla ilgili GenPipes mentorlarının girişlerine de ihtiyaç duyabiliriz. Bu GitHub deposu, RTD derleme ardışık düzenlerindeki tüm belgeleri içe aktarmak için kullanılabilir. Uyulması gerekiyorsa GenPipes depo kuralları ve doküman kaynağı yönetimi yönergeleri hakkında detaylı bilgi gerekebilir. Aksi takdirde, afaik standart olanlar kullanılabilir. Ayrıca ilgili kişi için GitHub hesabımı kullanarak örnek bir RTD kod deposu kurulumunun demosunu yapabilirim. Örneğin, https://gpdocs.readthedocs.io/en/latest/. Bu, bu teklif için oluşturduğum örnekleyicidir.)
Önceki adımdaki inceleme ve analize göre, önerilen GenPipes Belge yapısı / dizininin sağlam bir iskeletini oluşturun ve RTD sitesine yerleştirin
- GitHub deposu oluşturmayı (örneğin Sphinx araçlarıyla) ve temel belge dosyalarını içerir
- Bu kapsamda, çeşitli bölümler / bilgi akışları için hem yeni kullanıcıları hem de tecrübeli kullanımları göz önünde bulunduran yeni bir TOC oluşturma süreci var.
Barebones iskelet TOC'sini inceleyin / onay alın
GenPipes'in GSoD değerlendirme aşamasında RTD'de barındırılan bu örnekle GenPip'ler için değer oluşturmaya çalıştım. Bunun yalnızca demo amaçlı olduğunu, korumalı bağlantı olduğunu ve henüz RTD'de herkese açık olarak listelenmediğini lütfen unutmayın. Listeye alınıp alınmamam fark etmeksizin, bu demo GenPipes RTD çalışmasını hızlı bir şekilde başlatmak için kullanılabilir. c3g/GenPipes GitHub deposundaki kaynakları daha önce kontrol ettim. Mentorlar Rola ve Hector, daha önce Skype "ekranı paylaşma" tartışması sırasında bunu beğendi. Ben de GSoD Tanrılarının da bunu görmek isteyebileceğini düşündüm. Şimdilik sağlam bir iskelet. Ama 30 Temmuz'a kadar vakit bulduğumda güncellemeyi planlıyorum.
https://genpipes.readthedocs.io/en/latest/
2. Adım: GenPipes Dokümanı v0.9 doküman kümesi oluşturma
GSoD zaman çizelgelerini göz önünde bulundurarak RTD'de barındırmak için hangi mevcut veya mevcut GenPipes dokümanlarının içe aktarılabileceğini, bağlanabileceğini veya Sphinx/rst tabanlı dokümanlara dönüştürülebileceğini belirleyin.
Gerekirse, tanımlanan dokümanları rst biçimine dönüştürün, uygun durumlarda yenilerini oluşturun, mümkün olan / ilgili olan her şeyi yeniden kullanın.
- ReadTheDokümanlar'da Kavram Kanıtı olarak ayarlanan bu ilk dokümanı içe aktarın ve korunan bir depo olarak barındırın. İncelemeye/resmi geçiş yapılana 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ğı ayrıntılandırın, inceleyin ve yayınlayın
Önerilen GenPipes yeni doküman yapısının ayrıntılarını GenPipes TOC'sine girin. İlk birkaç belgenin yanı sıra daha fazla belge (GenPipes Readme), Concepts, Tutorials vb. ekleyin.
TOC'de yeni kullanıcılara, deneyimli GenPipes kullanıcılarına, GenPipes geliştiricilerine vb. hitap etmek için net ayrıntılar ekleyin.
GenPipes dokümanların nasıl sağlanabileceği, düzenlenebileceği ve C3G'nin dokümanlara katkıda bulunan harici kullanıcılar için buna izin verip vermeyeceğini belirlemek üzere RTD (sfenks derlemeleri) üzerinden kısmi otomasyon içeren bir çalışma sürecini tartışın. Bu, doküman güncellemeleri için kodlama yönergelerine benzer bazı yönergeler oluşturulmasını gerektirebilir. Daha fazla alt adım gerektirebilir. Örneğin, GenPipes dokümanlarında PR onayından önce yazım denetimini otomatik hale getirin.
Bildirme
Son olarak, deneyimlere, günlüklere ve mentorlardan gelen geri bildirimlere dayalı olarak GSoD için bir rapor oluşturun.
Diğer düşünceler
Uygun durumlarda, gelecekte (3 aydan sonrası) GenPip'ler için bu hizmetin daha uzun bir süre boyunca sağlanmasına yardımcı olabilirim. Ya da gerekirse başkalarını da bu konuda eğitin. Bunu, ilk 3 ayın sonucuna göre belirleyebiliriz.
Ayrıca, projeyle ilgili ek bir fikir de öneririm. Projeye kolayca giriş yapılmasına yardımcı olacak GenPipes 3 sayfalık bir özetin hazırlanması. Günümüzde yeni bir kullanıcının GenPipes'i kullanmaya başlamadan önce bir sürü adım atması gerekiyor. Dokümanlar iyi ancak dağınık durumda ve yeni kullanıcılar için elverişli değil. Bunu 3 ay içinde yapıp yapamayacağımı bilmiyorum ama denemek isterim.
Aynı teklifi ve nasıl ortaya çıktığını (geçmişi) https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing adresinden de görüntüleyebilirsiniz.