Mevcut aşama:
Belge geliştirme Zaman çizelgesini inceleyin.
Sezon, Google Açık Kaynak Programları Ofisi tarafından yönetilen bir sürdürülebilirlik programıdır. Dokümanlar Sezonunun hedefleri şunlardır:
- Proje sorunlarını belgelerle çözmek için açık kaynak projelere destek sağlama
- Teknik yazarlara açık kaynak konusunda deneyim kazanma fırsatı sunun
- Açık kaynak, doküman ve teknik yazım konusunda farkındalık oluşturun
- Açık kaynak belgelerindeki etkili metriklerle ilgili bilgileri toplama ve paylaşma
Dokümanlar Sezonu hakkında daha fazla bilgiyi programın web sitesinde bulabilirsiniz.
2022 programına genel bakış
Dokümanlar Sezonu nasıl çalışır?
Dokümanlar Dönemi'nde kuruluşlar proje teklifi göndererek başvuru yapar. Proje teklifi şunları içerir:
- Kuruluşla ilgili bilgiler
- Projenin karşılaştığı sorunun açıklaması
- Projenin bu problemi çözmek için belgeleri nasıl kullanacağı
- Projenin belgelerinin (metriklerin) etkinliğini nasıl ölçeceği
- İş için takvim
- Proje bütçesi
- Kuruluşun benzer programlardaki deneyimi veya Dokümanlar Mevsimi yöneticilerinin projesini ve sorununu anlamasına yardımcı olacak her türlü ek bilgi
Kuruluşlar programa kabul edildikten sonra doğrudan kendi teknik yazarlarını istihdam ediyor ve işe alıyor. Season of Docs kuruluşlara fon sağlamak için Open Collective'i kullanıyor ve kuruluşlar, Open Collective aracılığıyla teknik yazarlara ödeme yapıyor. Proje bütçeleri ve ödemeler şeffaftır; bütçeler Season of Docs sitesinde bulunan kuruluş proje tekliflerine dahildir ve ödemeler Season of Docs Open Collective hesabı bölümünde görülebilir.
Kuruluşlar, örnek olay raporlarını gönderdiklerinde programı başarıyla tamamlamış olarak kabul edilir. Kuruluşlardan ayrıca program süresince aylık değerlendirmeler yapmaları ve programın tamamlanmasından sonraki yıl boyunca üç ayda bir yapılan takip anketlerini tamamlamaları istenir.
2022'nin Öne Çıkanları
"Yeni belge yayınlandıktan sonra Casbin ve Casdoor'a yapılan günlük ziyaretler neredeyse iki katına çıktı ve hemen çıkma oranları yaklaşık %30 düştü."—Casbin
"Bu projenin güzel bir sonucu, [teknik yazarlarımızın] topluluğumuzda liderlik rollerine dönüşmesini görmek oldu. Şu anda bu iki katılımcı da çalışma grubu ve topluluk toplantılarını yönetmenin yanı sıra projelerimizin tasarımına ve bakımına da katkıda bulunuyor." —moja-global
"[GSoD], düzenli kurulumda oldukça zor olan, OpenMined'e etkin bir şekilde OS katkıda bulunmayı sürdüren ve mükemmel bir iş deneyimi yaşadığımız iki yetenekli teknik yazarı işe almamıza yardımcı oldu." - OpenMined
"Ayrıca bu yeni kılavuz, yeni başlayanların sayısal kütle spektrometrisini hesaplamasını çok daha kolay hale getiriyor. Bu noktayı açıklamak gerekirse: CZI hibesi, geçmişte kısıtlı imkanları olan bireylere de çeşitli yardımlar sağlıyor. Bazı ödül sahipleri, altı haftalık staj dönemlerine hızlı bir başlangıç yapmak için yeni OpenMS kılavuzunu kullandı ve yeni kılavuzla ilgili olumlu incelemeler yaptılar." —OpenMS
2022 özet verileri
2022 yılında Dokümanlar Sezonu programına 67 başvurudan 31 proje kabul edildi ve 30 proje programı başarıyla tamamladı. Kabul edilen 31 kuruluştan 17'si tekrar başvurdu.
Kabul edilen 31 projede 58 teknik yazar bulundu. 190'dan fazla teknik yazar, Dokümanlar'ın Sezonu GitHub deposunda, iletişim bilgilerini ve portföylerinin bağlantılarını ekleyerek programa katılmakla ilgilendiğini belirtti.
2022 programı için:
- Kuruluşların% 100'ü başvuru süreciyle ilgili olumlu bir deneyim yaşamıştır
- Kuruluşların% 100'ü program web sitesi dokümanları/içeriği ile ilgili olumlu deneyim yaşamıştır
- Kuruluşların% 93'ü programla ilgili olumlu bir deneyim yaşamıştır
- Kuruluşların% 90'ı belgeleme projelerinin başarılı olduğunu düşünüyordu
Kuruluşlar hakkında
Dokümanlar 2022 Sezonu'na katılan kuruluşlar, çok çeşitli açık kaynak projeleri temsil etti. 2022 grubunda şunlar yer alıyordu:
- AsyncAPI ve SpyderIDE gibi geliştirme araçları
- Julia, LFortran, R ve p5.js gibi programlama dilleri ve çerçeveleri
- CERN-HSF ve SymPy gibi bilimsel projeler
- Mautic, Open Food Facts, Talawa ve Ushahidi gibi son kullanıcı uygulamaları
- ExpressLRS ve Open-RMF gibi donanım ve robot bilimi projeleri
- GeomScale, GeomStats, OpenMined ve Weaviate gibi veri projeleri
- cert-manager, NimbleEdge ve Cilium gibi bulut ve altyapı projeleri
Projelerle ilgili herhangi bir meta veri toplamadık (kurulum tarihi, katkıda bulunanların coğrafi dağılımı, katkıda bulunanların sayısı veya kullanıcı tabanının büyüklüğü gibi).
Projelerden hangi açık kaynak lisansını kullandıklarını sorduk.
Belge projeleri hakkında
Belgeleme sorunları
Kuruluşların 2022 programında belgelerle çözmeyi umdukları en önemli sorunlar arasında şunlar vardı:
Kuruluşların birden fazla belge sorunu bildirebileceğini unutmayın. Daha ayrıntılı bilgi için orijinal proje tekliflerine ve her kuruluş için eksiksiz örnek olaylara bağlantı veren Dokümanlar 2022 Sezonu sonuçları sayfasına göz atın.
Oluşturulan belge türleri
"Nasıl yapılır?" belgeleri, 2022 örnek olaylarında en çok söz edilen belge türü oldu.
Örnek olaylarda bahsedilen diğer belge türleri şunlardır:
- Hızlı Başlangıç
- Sözlük
- SSS
- Bilgi tabanı
- Bileşenler
- Blog/sosyal medya içeriği
- Bakım kılavuzu
Bu kategorilerden bazıları bulanıktır ve tek bir belgeleme projesi birden fazla belge türü veya özellik içerebilir.
Daha ayrıntılı bilgi için orijinal proje tekliflerine ve her kuruluş için eksiksiz örnek olaylara bağlantı veren Dokümanlar 2022 Sezonu sonuçları sayfasına göz atın.
Bütçe sayısı
Ortalama bütçe isteği 11.679 TL ve ortanca değer 12.150 TL'dir. Beş kuruluş mevcut en yüksek hibeyi (15.000 ABD doları) talep etti ve aldı ve üç kuruluş en düşük hibeyi talep etti (5.000 ila 7.000 ABD doları).
Metrikler
Vaka analizlerinde ana hatlarıyla açıklanan projeler, belgeleme projelerinin başarısını ölçmek için kullandıkları metriklerden bahseder.
En çok önerilen metrikler şunlardır:
Önerilen diğer metrikler şunlardır:
- Diğer belgeler çekme istekleri/katkıları
- Belge sayfalarında daha fazla doğrudan geri bildirim
- Sayfada geçirilen süre
- Ortaya çıkan sorunlar (kullanım proxy'si olarak)
- Forumlardaki katılımcılar
- İş ortağı/gönüllü/entegrasyon sayısı
- Daha düşük hemen çıkma oranı
- Toplulukta farkındalık arttı.
Teknik yazı yazma projelerini tamamlama ve örnek olayları gönderme arasındaki kısa zaman nedeniyle 2022 grubunun çoğu, örnek olaylarını gönderdikleri sırada ilk metriklerine ulaşılıp ulaşılmadığını belirlemek için yeterli veri toplayamamıştı.
2023'te takip anketlerinin yanıtlarını aldıkça bu raporu hangi projelerin metriklerinin ulaştığı veya metriklerini düzenlediği hakkında bilgi eklemek için güncelleyeceğiz.
Daha ayrıntılı bilgi için orijinal proje tekliflerine ve her kuruluş için eksiksiz örnek olaylara bağlantı veren Dokümanlar 2022 Sezonu sonuçları sayfasına göz atın.
Teknik yazarlarla çalışma
Dokümanlar Sezonu programında, projelerin doğrudan teknik yazarları işe alması, mülakat yapması, işe alması ve ödeme yapması beklenir. Teknik yazarlar GitHub depomuzdaki Dokümanlar Mevsimi tarafından korunan dizine kendilerini ekleyebilirler ancak Sezon Dokümanlar ekibi, teknik yazarları değerlendirmez veya bunlarla ilgili öneride bulunmaz.
Açık kaynak projeler için teknik yazar işe almayla ilgili en iyi uygulamalar
Projelerden işe alma, işe alma ve teknik yazarlarla çalışma ile ilgili en iyi uygulamalarını paylaşmaları istendi. Başlıca öneriler şunlardır:
İşe Alım
- Daha az adayla mülakat yapın ve yalnızca öz geçmişleri incelemek yerine canlı alıştırma oturumu yapın
- Projenizin dilinde ya da kullandığı araçlarda yeterlilikten çok yazılı ve sözlü iletişim becerilerine değer verin
- Teknik yazarın projenizle çalışmak için gereken alan bilgisini nasıl edineceği hakkında doğrudan sorular sorun
- Projenizin misyonuna hevesli olan ve temel açık kaynak değerlerini paylaşan kişilerin proje boyunca motivasyonlarını koruma olasılığı daha yüksektir
- Farklı bakış açıları ve geçmişler projenize yardımcı olacağından, dünyanın her yerinden başvuru sahiplerine açık olun. Ancak, ihtilaflı çok sayıda saat diliminde yazar ve mentorların iyi bir iletişimi sürdürmek için çok fazla çaba gerektirebileceğini unutmayın.
İşe Alınacak Kişi Sayısı
- Teslimatları, ödeme planlarını ve belirli zaman taahhütlerini açıkça belirten bir sözleşme kullanın
- Projenizde çok fazla bilinmeyen varsa belge oluşturmaktan ayrı olarak keşif veya araştırma için bir ara hedef ekleyin
Koordinasyon ve iletişim
- Proje üzerinde çalışan herkesin bağlamı ve sonraki adımları anlamasını kolaylaştırmak için kararları toplantı günlüğü kaydını tutma
- Ne tür bir iletişim beklendiği ve ne sıklıkta (haftalık aramalar, günlük e-postalar veya bir sohbet kanalında durum güncellemeleri) konusunda net olun.
- Duyarlı olun ve yalnızca 'ne' değil, 'neden' sorularını da içeren net geri bildirimler verin.
- Teknik yazarlarınızı toplulukla bir araya getirerek bağlam sunmalarını ve çalışmalarını sosyalleştirmelerini sağlayın
Süreçler ve araçlar
- Dokümanlar Sezonu programının ötesine geçecek ve tüm topluluğun katkıda bulunabileceği bir doküman süreci oluşturun.
- Belge incelemesi en az kod incelemesi kadar sürer ve en az kod incelemesi kadar zaman alır. Bu inceleme için yeterince zaman ayırdığınızdan emin olun.
Bazı öneriler daha net olacak şekilde düzenlendi ve kısaltıldı.
2021 programında olduğu gibi, Dokümanlar 2022 Sezonundaki teknik yazarların çoğu, doğrudan birlikte çalıştıkları kuruluşlara başvurdu.
Teknik yazarlarla çalışırken sık karşılaşılan sorunlar
2022 programında daha az sayıda projede teknik yazarlarla çalışırken sorun bildirildi. Hastalık, tam zamanlı bir işte çalışma veya zamanı yetiştirememe nedeniyle programın en büyük sorunu teknik yazarların programı tamamlayamamasıydı.
Bir proje, dokümantasyon projelerinin Google Summer of Code kapsamında yapılan işlere bağlı olduğunu ve bu bağımlılıkları yönetmenin zor olduğunu bildirdi. Başka bir projede ise teknik yazarının belgelemek için ihtiyaç duyduğu donanım, yazarın ülkesindeki Savunma Bakanlığı tarafından el konulmasına ve ithal edilmesi mümkün olmadığında zorluklarla karşılaştı.
Takip anketleri
Mayıs, Ağustos ve Kasım 2023'te 2022 katılımcılarına üç takip anketi gönderilecektir. Sonuçlar bize ulaştıkça bu bölümü güncelleyeceğiz.
Gelecekteki sorular
Her zaman olduğu gibi, açık kaynakta belgeleme hakkında ne kadar çok şey öğrenirsek o kadar çok şey öğrenmek istiyoruz!
Gelecek sezonlarda:
- Proje yaşı, topluluğun büyüklüğü ya da dil ve belge ihtiyaçları arasındaki bağıntıları aramak için daha fazla proje meta verisi toplayın
- Paylaşılabilir şablonlar halinde genelleştirilip dönüştürülemeyeceklerini görmek için belge projelerini analiz edin.
- Açık kaynak projelerde teknik yazarlarla mülakat yapmak için bir puan anahtarı oluşturun
Ele almak istediğimiz pek çok soru olsa da Dokümanlar Sezonu'na katılan açık kaynak proje yöneticilerinin ve yöneticilerinin zamanına saygı duymak istiyoruz. Programın en önemli önceliği, projelerin belgelerle ilgili sorunlarını çözmelerinde destek olmaktır.