Mevcut aşama:
Örnek olaylar yayınlandı. Zaman çizelgesine bakın.
Dokümanlar Sezonu, 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:
- Proje sorunlarını dokümanlarla çözmek için açık kaynaklı projelere destek sunma
- Teknik yazarlara açık kaynak konusunda deneyim kazanma fırsatı verin
- Açık kaynak, dokümanlar ve teknik yazım hakkında farkındalık oluşturma
- Açık kaynak dokümanlarındaki etkili metrikler hakkında bilgi toplayabilir ve paylaşabilirsiniz.
Belge Sezonu hakkında daha fazla bilgiyi programın web sitesinde bulabilirsiniz.
2022 programına genel bakış
Season of Docs nasıl çalışır?
Belgeler Sezonu'na katılmak isteyen kuruluşlar proje teklifi göndererek başvuruda bulunur. Proje önerisi şunları içerir:
- Kuruluşla ilgili bilgiler
- Projenin karşılaştığı sorunun açıklaması
- Projenin, sorunu çözmek için dokümanları nasıl kullanacağı
- Projenin dokümanlarının etkinliğini nasıl ölçeceği (metrikler)
- Çalışmanın zaman çizelgesi
- Proje bütçesi
- Kurumun benzer programlardaki deneyimi gibi ek bilgiler veya Belgeler Sezonu yöneticilerinin projeyi ve sorunu anlamalarına yardımcı olacak başka bilgiler
Programa kabul edilen kuruluşlar, doğrudan kendi teknik yazarlarını işe alır. Season of Docs, kuruluşlara kaynak sağlamak için Open Collective'i kullanır ve kuruluşlar, teknik yazarlara Open Collective üzerinden ödeme yapar. Proje bütçeleri ve ödemeler ş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ın, vaka çalışması raporunu göndermesiyle program başarıyla tamamlanmış kabul edilir. Kuruluşlardan program süresince aylık değerlendirmeler ve program tamamlandıktan sonraki yıl içinde üç üç aylık takip anketi doldurmaları da istenir.
2022'nin Öne Çıkan Anları
"Yeni doküman 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 en sevindirici sonuçlarından biri, [teknik yazarlarımızın] topluluğumuzda liderlik rollerine yükseldiğini görmek oldu. Bu iki katkıda bulunan, 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], normal bir kurulumda oldukça zor olan iki yetenekli teknik yazar işe almamıza yardımcı oldu. Bu yazarlar, OpenMined'e 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 spektrometrisine yeni başlayanlar için çok daha kolay. Bu noktayı açıklamak için: CZI bursu, geçmişte dezavantajlı olan kişilere de burs sağlar. Bazı ödül sahipleri, altı haftalık staj dönemine hızlı bir başlangıç yapmak için yeni OpenMS kılavuzunu kullandı ve yeni kılavuz hakkında olumlu yorumlar yaptı." —OpenMS
2022 Özet verileri
2022'de Belgeler 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 daha önce başvuruda bulunmuş kuruluşlardı.
Kabul edilen 31 projede 58 teknik yazar işe alındı. 190'dan fazla teknik yazar, Dokümanlar Sezonu GitHub deposuna iletişim bilgilerini ve portföy 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üman projesinin başarılı olduğunu düşünüyor
Kuruluşlar hakkında
Dokümanlar Sezonu 2022'ye katılan kuruluşlar, çeşitli açık kaynak projelerini temsil ediyordu. 2022 kohortu şunları içeriyordu:
- 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 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) toplamadık.
Projelerden kullandıkları açık kaynak lisansı belirtmelerini istedik.
Belgeleme projeleri hakkında
Doküman sorunları
Kuruluşların 2022 programında dokümanlar sayesinde çö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 her kuruluşun orijinal proje tekliflerine ve tam örnek olaylarını içeren Dokümanlar Sezonu 2022 sonuçlar sayfasına bakın.
Oluşturulan doküman türleri
2022'deki örnek olaylarda en çok bahsedilen doküman türü kullanım kılavuzlarıydı.
Örnek çalışmalarda 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ı belirsizdir ve tek bir doküman projesi birden fazla doküman türü veya özelliği içerebilir.
Daha ayrıntılı bilgi için her kuruluşun orijinal proje tekliflerine ve tam örnek olaylarını içeren bağlantıların yer aldığı Dokümanlar Sezonu 2022 sonuçlar sayfasına bakın.
Bütçeler
Ortalama bütçe isteği 11.679 TL, medyan bütçe isteği ise 12.150 TL idi. Beş kuruluş, mevcut en yüksek hibeyi (15.000 ABD doları) talep etti ve aldı. Üç kuruluş ise en düşük hibeyi (5.000-7.000 ABD doları) talep etti.
Metrikler
Projeler, doküman projelerinin başarısını ölçmek için kullandıkları metrikleri vaka analizlerinde özetledi.
Önerilen en önemli metrikler şunlardır:
Önerilen diğer metrikler şunlardır:
- Daha fazla doküman alma isteği/katkı
- Doküman sayfalarında daha doğrudan geri bildirim
- Sayfada geçirilen süre
- Ortaya çıkan sorunlar (kullanım için proxy olarak)
- Forum katılımcıları
- İş ortağı/gönüllü/entegrasyon sayısı
- Hemen çıkma oranının azalması
- Toplulukta farkındalık artışı.
Teknik yazım projelerini tamamlama ile örnek olay gönderme arasındaki kısa süre nedeniyle 2022 kohortunun çoğu, örnek olaylarını gönderirken ilk metriklerinin karşılanıp karşılanmadığını belirlemek için yeterli veri toplayamadı.
2023'te takip anketlerinin yanıtlarını aldıkça, hangi projelerin metriklerine ulaştığını veya metriklerini düzelttiğini içeren bilgiler eklemek için bu raporu güncelleyeceğiz.
Daha ayrıntılı bilgi için her kuruluşun orijinal proje tekliflerine ve tam örnek olaylarını içeren Dokümanlar Sezonu 2022 sonuçlar sayfasına göz atın.
Teknik yazarlarla çalışma
Dokümanlar Sezonu programında, projelerin teknik yazarları doğrudan işe alması, mülakat yapması, işe alması ve ödeme yapması beklenir. Teknik yazarlar, kendilerini GitHub depomuzda Season of Docs tarafından yönetilen dizine ekleyebilir. Ancak Season of Docs ekibi, teknik yazarları incelemez veya tavsiye etmez.
Açık kaynak projeleri için teknik yazarlar işe almayla ilgili en iyi uygulamalar
Projelerden, teknik yazarları işe alma ve onlarla çalışmayla ilgili en iyi uygulamalarını paylaşması istendi. En çok önerilenler şunlardı:
İşe Alım
- Yalnızca özgeçmişleri incelemek yerine daha az sayıda adayla görüşün ve canlı alıştırma oturumu kullanın
- Projenizin dili veya araçları konusundaki yeterlilik 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 bağlı olan ve temel açık kaynak değerlerini paylaşan bir kişinin projenin tamamı boyunca motivasyonunu koruması daha olasıdır.
- Farklı bakış açıları ve geçmişlere sahip yazarlar projenize yardımcı olacağından dünyanın her yerinden başvuruları kabul edin. Ancak, farklı saat dilimlerinde bulunan yazar ve mentorlarla iyi iletişim kurabilmek için çok fazla çaba sarf etmeniz gerekebileceğini unutmayın.
İşe Alım
- Teslim edilecek öğeleri, ödeme planlarını ve belirli zaman taahhütlerini açıkça belirten bir sözleşme kullanın
- Projenizde bilinmeyen çok fazla şey varsa doküman oluşturma aşamasından ayrı bir keşif veya araştırma aşaması ekleyin
Koordinasyon ve iletişim
- Projede çalışan herkesin bağlamı ve sonraki adımları daha kolay anlamasını sağlamak için alınan kararları kaydeden bir toplantı günlüğü tutun
- Haftalık görüşmeler, günlük e-postalar veya sohbet kanalındaki durum güncellemeleri gibi hangi iletişimin ne sıklıkta beklendiği konusunda net olun.
- Hızlı yanıt verin ve yalnızca "ne"yi değil, "neden"i de içeren net geri bildirimler verin.
- Teknik yazarlarınızın bağlam bilgisi edinmesi ve çalışmalarını sosyalleştirmesi için onları daha geniş bir toplulukla tanıştırı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ümantasyon süreci oluşturun.
- Belge incelemesi, kod incelemesi kadar uzun sürer ve yoğundur. Bu işlem için yeterli zaman ayırdığınızdan emin olun.
Bazı öneriler, anlaşılır olması için düzenlendi ve kısaltıldı.
2021 programında olduğu gibi, Dokümanlar Sezonu 2022'deki teknik yazarların çoğu doğrudan birlikte çalıştıkları kuruluşlara başvurdu.
Teknik yazarlarla çalışırken karşılaşılan yaygın sorunlar
2022 programında, teknik yazarlarla çalışmayla ilgili sorun bildiren proje sayısı daha azdı. Hastalık, tam zamanlı iş veya zaman taahhüdünü yerine getirememe nedeniyle teknik yazarların programı tamamlayamaması en büyük sorundu.
Bir proje, doküman 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. Teknik yazarının belgelemesi gereken donanım, yazarın ülkesindeki Savunma Bakanlığı tarafından el konulduğunda ve içe aktarılamadığında başka bir projede de zorluklarla karşılaşıldı.
Takip anketleri
2022 katılımcılarına 2023'ün Mayıs, Ağustos ve Kasım aylarında üç takip anketi gönderilecek. Elde edilen sonuçlar bu bölümde paylaşılacak.
Gelecekteki sorular
Her zaman olduğu gibi, açık kaynak dokümanları hakkında ne kadar çok bilgi edinirsek o kadar çok öğrenmek istiyoruz.
Gelecek sezonlarda şunları yapmayı umuyoruz:
- Proje yaşı, topluluk büyüklüğü veya dil ile dokümanlar arasındaki ilişkileri incelemek için daha fazla proje meta verisi toplayın
- Paylaşılabilen şablonlar haline getirilip getirilemeyeceklerini görmek için doküman projelerini analiz edin.
- Açık kaynaklı projelerde teknik yazarlarla röportaj yapmak için bir değerlendirme ölçütü geliştirme
Araştırmak istediğimiz birçok soru olsa da Dokümanlar Sezonu'na katılan açık kaynak proje yöneticilerinin ve koruyucularının zamanını da göz önünde bulundurmak istiyoruz. Programın birincil önceliği, projelerin dokümantasyonla ilgili sorunlarını çözmelerine yardımcı olmaktır.