Season of Docs, Google Açık Kaynak Programları Ofisi tarafından yönetilen bir sürdürülebilirlik programıdır. Season of Docs'un hedefleri şunlardır:
- Açık kaynak projelerine destek vererek belgelerle proje sorunlarını çözme
- Teknik yazarlara açık kaynak konusunda deneyim kazanma fırsatı verin
- Açık kaynak, dokümantasyon ve teknik yazım konusunda farkındalık oluşturma
- Açık kaynak dokümanlarındaki etkili metrikler hakkında bilgi toplayıp paylaşma
Season of Docs hakkında daha fazla bilgiyi programın web sitesinde bulabilirsiniz.
2022 programına genel bakış
Season of Docs'un işleyiş şekli
Season of Docs'ta kuruluşlar, proje teklifi göndererek başvuruda bulunur. Proje teklifi şunları içerir:
- Kuruluş hakkında bilgiler
- Projenin karşılaştığı sorunun açıklaması
- Projenin, sorununu çözmek için dokümanlardan nasıl yararlanacağı
- Projenin dokümanlarının etkinliğini nasıl ölçeceği (metrikler)
- Çalışmanın zaman çizelgesi
- Proje bütçesi
- Kuruluşun benzer programlardaki deneyimi gibi ek bilgiler veya Season of Docs yöneticilerinin projeyi ve sorunu anlamasına yardımcı olacak diğer bilgiler
Programa kabul edilen kuruluşlar, kendi teknik yazarlarını doğrudan işe alır. Season of Docs, kuruluşları finanse etmek için Open Collective'i kullanır. Kuruluşlar, teknik yazarlara Open Collective üzerinden ödeme yapar. Proje bütçeleri ve ödemeleri şeffaftır. Bütçeler, Season of Docs sitesinde bulunan kuruluş proje tekliflerine dahil edilir ve ödemeler Season of Docs Open Collective hesabında görünür.
Kuruluşlar, başarı öyküsü raporlarını gönderdiklerinde programı başarıyla tamamlamış kabul edilir. Kuruluşlardan program süresince aylık değerlendirmeler yapmaları ve program tamamlandıktan sonraki yıl içinde üç aylık takip anketleri doldurmaları da istenir.
2022'de öne çıkanlar
"Yeni doküman yayınlandıktan sonra Casbin ve Casdoor'a yapılan günlük ziyaret sayısı neredeyse iki katına çıktı ve hemen çıkma oranları yaklaşık %30 düştü." - Casbin
"Bu projenin keyifli bir sonucu da [teknik yazarlarımızın] topluluğumuzda liderlik rollerine yükselmesini izlemek oldu. Her iki katkıda bulunan da artık çalışma grubu ve topluluk toplantılarına liderlik ediyor ve projelerimizin tasarımına ve bakımına katkıda bulunuyor." —moja-global
"[GSoD], normalde çok zor olan bir şekilde iki yetenekli teknik yazar işe almamıza yardımcı oldu. Bu yazarlar, OpenMined'a aktif olarak katkıda bulunmaya devam ediyor ve onlarla harika bir çalışma deneyimi yaşadık." —OpenMined
"Ayrıca, yeni kılavuz, hesaplamalı kütle spektrometrisi konusunda yeni olanlar için çok daha kolay. Bu noktayı açıklamak için: CZI hibesi, geçmişte ayrıcalıklı olmayan kişilere de burs sağlıyor ve bazı bursiyerler, altı haftalık staj dönemlerine hızlı bir başlangıç yapmak için yeni OpenMS kılavuzunu kullandı ve yeni kılavuz hakkında olumlu yorumlar yaptı." —OpenMS
2022 yılı özet verileri
2022'de Season of Docs programı, 67 başvurudan 31 projeyi kabul etti ve 30 proje programı başarıyla tamamladı. Kabul edilen 31 kuruluşun 17'si daha önce de başvurmuştu.
Kabul edilen 31 projede 58 teknik yazar çalıştı. 190'dan fazla teknik yazar, Season of Docs GitHub deposuna iletişim bilgilerini ve portfolyolarının bağlantılarını ekleyerek programa katılmak istediklerini belirtti.
2022 programı için:
- Kuruluşların% 100'ü başvuru süreciyle ilgili olumlu bir deneyim yaşadı.
- Kuruluşların% 100'ü, program web sitesi dokümanları/içeriğiyle ilgili olumlu bir deneyim yaşadı.
- Kuruluşların% 93'ü programla ilgili olumlu bir deneyim yaşadı.
- Kuruluşların% 90'ı dokümantasyon projelerinin başarılı olduğunu düşünüyor.
Kuruluşlar hakkında
Season of Docs 2022'ye katılan kuruluşlar, çeşitli açık kaynak projelerini temsil ediyordu. 2022 grubu şunları içeriyordu:
- AsyncAPI ve SpyderIDE gibi geliştirme araçları
- Julia, LFortran, R ve p5.js gibi programlama dilleri ve çerçeveler
- 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 robotik 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 (ör. kuruluş tarihi, katkıda bulunanların coğrafi dağılımı, katkıda bulunanların sayısı veya kullanıcı tabanının boyutu) toplamıyoruz.
Projelerden hangi açık kaynak lisansını kullandıklarını belirtmelerini istedik.
Belgeleme projeleri hakkında
Belgeleme sorunları
Kuruluşların 2022 programında dokümanlarla çözmeyi umduğu en önemli sorunlar şunlardı:
Kuruluşların birden fazla doküman sorunu bildirebileceğini unutmayın. Daha ayrıntılı bilgi için Season of Docs 2022 sonuçlar sayfasını inceleyin. Bu sayfada, orijinal proje tekliflerine ve her kuruluş için tam kapsamlı örnek olay çalışmalarına bağlantılar yer almaktadır.
Oluşturulan doküman türleri
2022'deki örnek olaylarda en sık bahsedilen doküman türü, nasıl yapılır dokümanları oldu.
Vaka çalışmalarında bahsedilen diğer doküman türleri şunlardır:
- Hızlı başlangıç kılavuzu
- Sözlük
- SSS
- Bilgi Bankası
- Bileşenler
- Blog/sosyal medya içeriği
- Bakımcı kılavuzu
Bu kategorilerin bazıları net değildir ve tek bir dokümantasyon projesi birden fazla dokümantasyon türü veya özelliği içerebilir.
Daha ayrıntılı bilgi için Season of Docs 2022 sonuçlar sayfasını inceleyin. Bu sayfada, orijinal proje tekliflerine ve her kuruluş için tam kapsamlı örnek olay çalışmalarına bağlantılar yer almaktadır.
Bütçeler
Ortalama bütçe isteği 11.679 ABD doları, medyan ise 12.150 ABD dolarıydı. Beş kuruluş, mevcut en yüksek hibeyi (15.000 ABD doları) talep edip aldı. Üç kuruluş ise en düşük hibeyi (5.000-7.000 ABD doları) talep etti.
Metrikler
Vaka analizlerinde, dokümantasyon projelerinin başarısını ölçmek için kullandıkları metrikleri belirtirler.
En çok önerilen metrikler şunlardı:
Önerilen diğer metrikler arasında şunlar yer alıyordu:
- Daha fazla doküman çekme isteği/katkı
- Doküman sayfaları hakkında daha doğrudan geri bildirim
- Sayfada geçirilen süre
- Kullanım için proxy olarak kullanılan sorunlar
- Forum katılımcıları
- İş ortağı/gönüllü/entegrasyon sayısı
- Düşük hemen çıkma oranı
- Toplulukta farkındalığın artması
Teknik yazım projelerinin tamamlanması ile örnek olayların gönderilmesi arasındaki kısa süre nedeniyle, 2022 grubunun çoğu, örnek olaylarını gönderirken ilk metriklerinin karşılanıp karşılanmadığını belirlemek için yeterli veriyi toplayamamıştı.
2023'te takip anketlerine yanıtlar aldıkça bu raporu güncelleyerek hangi projelerin metriklerine ulaştığı veya metriklerini revize ettiği hakkında bilgi ekleyeceğiz.
Daha ayrıntılı bilgi için Season of Docs 2022 sonuçlar sayfasını inceleyin. Bu sayfada, orijinal proje tekliflerine ve her kuruluş için tam kapsamlı örnek olay çalışmalarına bağlantılar yer almaktadır.
Teknik yazarlarla çalışma
Season of Docs programında projelerin teknik yazarları doğrudan işe alması, mülakat yapması ve ödeme yapması beklenir. Teknik yazarlar, GitHub depomuzda Season of Docs tarafından tutulan dizine kendilerini ekleyebilir. Ancak Season of Docs ekibi, teknik yazarları incelemez veya tavsiye etmez.
Açık kaynak projeleri için teknik yazarların işe alınmasıyla ilgili en iyi uygulamalar
Projelerden, teknik yazarları işe alma, çalıştırma ve işe almayla ilgili en iyi uygulamalarını paylaşmaları istendi. En çok önerilenler:
İşe Alım
- Daha az sayıda adayla görüşme yapın ve yalnızca CV'leri incelemek yerine canlı bir uygulama oturumu kullanın.
- Projenizin dilinde veya araçlarında uzmanlık yerine yazılı ve sözlü iletişim becerilerine değer verin.
- Teknik yazarın projenizle çalışmak için gerekli alan bilgisini nasıl edineceği hakkında doğrudan sorular sorun.
- Projenizin misyonuna ilgi duyan ve temel açık kaynak değerlerini paylaşan bir kişi, proje boyunca motivasyonunu korumaya daha yatkındır.
- Dünyanın her yerinden gelen adaylara açık olun. Farklı bakış açıları ve geçmişler projenize yardımcı olur. Ancak çok fazla çakışan saat dilimlerinde yazarların ve mentörlerin olması, iyi iletişimi sürdürmek için çok fazla çaba gerektirebilir.
İşe Alım
- Teslim edilecek içerikleri, ödeme planlarını ve belirli zaman taahhütlerini açıkça belirten bir sözleşme kullanın.
- Projenizde çok fazla bilinmeyen varsa doküman oluşturma dışında keşif veya araştırma için bir kilometre taşı ekleyin.
Koordinasyon ve iletişim
- Kararları kaydeden bir toplantı günlüğü tutarak projede çalışan herkesin bağlamı ve sonraki adımları anlamasını kolaylaştırın.
- Hangi iletişimin ne sıklıkta beklendiği konusunda net olun. Örneğin, haftalık görüşmeler, günlük e-postalar veya sohbet kanalında durum güncellemeleri.
- Yanıt verin ve yalnızca "ne" sorusunun değil, "neden" sorusunun cevabını da içeren net geri bildirimler verin.
- Teknik yazarlarınızı daha geniş bir toplulukla buluşturarak onlara bağlam sunun ve çalışmalarını paylaşmalarını sağlayın
Süreçler ve araçlar
- Season of Docs programının ötesine geçecek ve tüm topluluğun katkıda bulunabileceği bir dokümantasyon süreci oluşturun.
- Doküman incelemesi, kod incelemesi kadar uzun sürer ve aynı derecede kapsamlıdır. Bu nedenle, doküman incelemesi için yeterli zaman ayırdığınızdan emin olun.
Bazı öneriler, daha anlaşılır olması için düzenlenip kısaltıldı.
2021 programında olduğu gibi, Season of Docs 2022'deki teknik yazarların çoğu doğrudan çalıştıkları kuruluşlara başvurdu.
Teknik yazarlarla çalışırken karşılaşılan yaygın sorunlar
2022 programında, teknik yazarlarıyla çalışırken sorun yaşadığını bildiren proje sayısı azaldı. Teknik yazarların hastalığı, tam zamanlı işe başlaması veya zaman taahhüdünü karşılayamaması nedeniyle programı tamamlayamaması en büyük sorun oldu.
Bir proje, dokümantasyon projesinin Google Summer of Code kapsamında yapılan çalışmalara bağlı olduğunu ve bu bağımlılıkların yönetilmesinin zor olduğunu bildirdi. Başka bir projede ise teknik yazarın belgelemesi gereken donanıma yazarın ülkesindeki Savunma Bakanlığı tarafından el konulduğu ve donanım ithal edilemediği için zorluklar yaşandı.
Takip anketleri
2022'deki katılımcılara Mayıs, Ağustos ve Kasım 2023'te üç takip anketi gönderilecek. Bu bölümü, sonuçlar alındıkça güncelleyeceğiz.
Gelecekteki sorular
Her zaman olduğu gibi, açık kaynakta dokümanlar hakkında ne kadar çok şey öğrenirsek o kadar çok şey öğrenmek istiyoruz.
Gelecek sezonlarda şunları yapmayı planlıyoruz:
- Proje yaşı, topluluk boyutu veya dil ile dokümantasyon ihtiyaçları arasındaki korelasyonları aramak için daha fazla proje meta verisi toplama
- Paylaşılabilir şablonlara dönüştürülüp dönüştürülemeyeceklerini görmek için dokümantasyon projelerini analiz etme
- Açık kaynak projelerde teknik yazarlarla mülakat yapmak için bir puan anahtarı geliştirme
İncelemek istediğimiz birçok soru olsa da Season of Docs'a katılan açık kaynak proje yöneticilerinin ve bakımcılarının zamanına saygı duymak istiyoruz. Programın en önemli önceliği, projelerin belgelerle ilgili sorunlarını çözmelerine yardımcı olmaktır.