Mevcut aşama:
2021 Belge Sezonu programı 14 Aralık 2021'de sona erdi. Zaman çizelgesine bakın.
Season of Docs hakkında
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.
2021 programına genel bakış
2021 program değişiklikleri
2019 ve 2020'de kuruluşlar ile teknik yazarlar Dokümanlar Sezonu programına ayrı ayrı başvurdu ve teknik yazarlar, Dokümanlar Sezonu program yöneticileri tarafından kuruluşlarla eşleştirildi. Kuruluşların sağladığı mentorlar, teknik yazarlarla birlikte çalıştı. Yazarlar, bulundukları yere göre çalışmaları için ek ücret aldı. Programda teknik yazarlar, mentorlar ve kuruluş yöneticilerinin programa katılımlarından memnun olup olmadıkları ölçüldü ancak dokümantasyon sonuçları ölçülmedi.
2021'de Dokümanlar Sezonu ekibi, odak noktasını doküman sonuçlarını ölçmeye kaydırarak ve kuruluşlar ile teknik yazarlara daha fazla esneklik tanıyarak programda önemli değişiklikler yaptı.
- Bütçe ve önerilen metrikler dahil olmak üzere proje teklifleriyle başvuran kuruluşlar
- Teknik yazarlar artık kuruluşlarla eşleştirilmek için Google üzerinden değil, doğrudan kabul edilen kuruluşlara başvuruyor.
- Kabul edilen kuruluşlar, Open Collective aracılığıyla bağış aldı ve bu bağışları teknik yazarlara ödeme yapmak için kullandı
- Teknik yazarlara ödenecek ücret kuruluşlar tarafından belirlendi
- Kuruluşlar nihai değerlendirmeleri ve örnek olaylarını gönderdi ve takip anketlerini yanıtladı
2021 genel bulguları
Kuruluşlar
- 2021 programındaki değişiklikler, başvuru yapan kuruluş sayısının azalmasına neden oldu (2021'de 2020'ye kıyasla% 30 daha az kuruluş başvuruda bulundu). Ancak 2021'deki kuruluş yöneticileri, programdan 2020'deki yöneticilere kıyasla biraz daha memnundu (%93 ve %91).
Sorunlar, doküman türleri ve metrikler
- Çoğu proje, geliştirici yükünü azaltmak (sorun/soru sayısını azaltarak) ve/veya proje katılımını artırmak (proje kullanıcıları veya katkıda bulunanlar tarafından) için doküman oluşturmaya odaklandı.
- Kabul edilen kuruluşların% 50'si eğitim veya nasıl yapılır içerikleri oluşturdu.
- Kabul edilen kuruluşların% 50'sinden fazlası, mevcut dokümanlarının eksik, dağınık veya güncel olmadığını düşünüyordu.
- Projeler genellikle dokümanların etkinliğini etkileşimler (özellikle daha az sorun, daha fazla doküman ziyaretçisi ve proje katılımı) üzerinden ölçmek istiyordu.
- Kasım 2022 itibarıyla, 30 projeden 25'i yanıt verdi:
- 18 proje, orijinal metriklerine ulaştığını belirtti
- 5 proje, gözden geçirilmiş metrikleri karşıladı
- 2 projede henüz bir şey söylemek için çok erken olduğu söylendi
Programa katılım
- Teknik yazarları işe alma, işe alma ve onlara ödeme yapma, kuruluş yöneticileri için programın en zor kısmıydı.
- Kasım 2022 itibarıyla, 30 kuruluştan 24'ü yanıt verdi:
- 18 kuruluş, Dokümanlar Sezonu teknik yazarlarıyla çalışmaya devam ediyordu (devam eden bir katkıda bulunan veya soruları yanıtlayan bir kaynak olarak)
- 4 kuruluş, Dokümanlar Sezonu teknik yazarlarıyla ücretli olarak çalışıyordu
- 18 kuruluş, Dokümanlar Sezonu teknik yazarlarıyla çalışmaya devam ediyordu (devam eden bir katkıda bulunan veya soruları yanıtlayan bir kaynak olarak)
2021'de öne çıkanlar
- Birden fazla proje, teknik yazarlarının Dokümanlar Sezonu programının sona ermesinden sonra projeleriyle çalışmaya devam etmek istediğini belirtti.
- Metanorma'ya çok sayıda nitelikli teknik yazar başvurdu. Bu nedenle, program sırasında Dokümanlar Sezonu destekli yazarla birlikte çalışacak ek bir yazar işe almak için eşleşen fonlar buldular.
- Moja Global, topluluğun dokümanlar konusunda çok aktif olduğunu fark etti ve daha fazla katkıda bulunan kullanıcının proje dokümanlarına katılmasına olanak tanımak için yeni bir Dokümanlar Çalışma Grubu oluşturdu.
2021 özet verileri
2021'de 82 kuruluş başvuruda bulundu ve 30 açık kaynak kuruluşu programa kabul edildi. (Seçim ölçütleri için Uygulamanızı Oluşturma kılavuzuna bakın.) Katılan kuruluşların tam listesini Belge Sezonu web sitesinde bulabilirsiniz. Kabul edilen 30 kuruluşun tamamı, 2021 programına katılımlarını tamamlamak için nihai örnek olay raporlarını gönderdi.
Kuruluşlar hakkında
Dokümanlar Sezonu 2021'e katılan kuruluşlar, çeşitli açık kaynak projelerini temsil ediyordu. 2021 kohortu şunları içeriyordu:
- Julia, Perl ve R gibi büyük dil projeleri
- Eğitim, iklim, fintech, sağlık, kütüphane hizmetleri, makine öğrenimi, kütle spektrometrisi, kamu sözleşmeleri ve robotik alanlarında projeler
- Kaos mühendisliği araçları, fuzzer'lar, chatbot SDK'ları, yazılım bileşimi analiz ardışık düzenekleri, performans izleme araçları ve görsel programlama araçları gibi geliştirici odaklı projeler
- Redocly ve Metanorma gibi doküman araçları için doküman projeleri
Python ekosistemi projeleri en büyük alt kategoriydi. 2021 kohortu ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite ve SymPy'yi içeriyordu.
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.
2021'de kuruluşlar tarafından belirtilen doküman sorunları hem açık kaynak projelerde hem de genel olarak teknik dokümanlarda çok yaygın sorunlardır.
Kuruluşların 2021 programında çözmeyi umduğu en önemli sorunlar şunlardı:
Kuruluşların birden fazla doküman sorunu bildirebileceğini unutmayın. Daha fazla bilgi için her kuruluşun tam örnek olaylarının bağlantılarını içeren Dokümanlar Sezonu 2021 sonuçlar sayfasına bakın.
Oluşturulan doküman türleri
2021'deki örnek olaylarda en çok bahsedilen doküman türü eğitici içeriklerdi.
Örnek çalışmalarda bahsedilen diğer doküman türleri arasında kod olarak doküman ardışık düzeni, diyagram, sözlük, stil kılavuzu, SSS, uluslararasılaştırma, Codelab, içerik modeli, modüller, kavram dokümanları, hata mesajları, kullanıcı araştırması, readme, bilgi bankası yer alıyor.
Bu kategorilerin bazıları belirsizdir ve tek bir doküman projesi birden fazla doküman türü veya özelliği içerebilir.
Belge türlerini planlama rehberi olarak Diátaxis çerçevesini kullanan çeşitli projelere özellikle referans verilmiştir.
Daha fazla bilgi için her kuruluşun tam örnek olaylarının bağlantılarını içeren Dokümanlar Sezonu 2021 sonuçlar sayfasına bakın.
Bütçeler
2021'de ortalama bütçe isteği 10.200 TL, medyan bütçe isteği ise 10.000 TL idi. Yalnızca üç kuruluş mümkün olan en yüksek hibeyi (15.000 ABD doları) talep edip aldı ve üç kuruluş da mümkün olan en düşük hibeyi (5.000 ABD doları) talep etti.
Metrikler
Projeler, doküman projelerinin başarısını ölçmek için kullandıkları metrikleri vaka analizlerinde özetlemiştir.
Önerilen en önemli metrikler şunlardır:
Önerilen diğer metrikler arasında GitHub yıldızları, Sayfada geçirilen süre, E-posta listesi dönüşümleri, Nitel kullanıcı testi, Forumlardaki katılımcı sayısı, İş ortağı/gönüllü/entegrasyon sayısı yer aldı.
Teknik yazım projelerini tamamlama ile örnek olay gönderme arasındaki kısa süre nedeniyle 2021 kohortunun çoğu, ilk metriklerinin karşılanıp karşılanmadığını belirlemek için yeterli veri toplayamadı.
Daha fazla bilgi için her kuruluşun tam örnek olaylarının bağlantılarını içeren Dokümanlar Sezonu 2021 sonuçlar sayfasına bakın.
Teknik yazarlarla çalışma
2021'de Dokümanlar Sezonu programında yapılan en büyük değişiklik, projelerin teknik yazarlarla çalışma şekliyle ilgiliydi. Önceki sezonlarda teknik yazarlar doğrudan Google'a başvurur, program yöneticileri tarafından projelerle eşleştirilir ve doğrudan Google'dan sabit bir sübvansiyon alırdı.
2021'de teknik yazarlar doğrudan projelere başvurdu ve projeler teknik yazarlara ödenecek ücreti belirledi. Ödemeler, Dokümanlar Sezonu Open Collective fonu aracılığıyla yapıldı.
2021 programına katılan projelerin çoğu, teknik yazarları işe alma konusunda çok az deneyime sahipti veya hiç deneyimi yoktu. Birçok proje, sürecin bu kısmının daha fazla desteğe ihtiyaç duyduğunu belirtti. Bu geri bildirime yanıt olarak Dokümanlar Sezonu ekibi, program kılavuzuna teknik yazar sözleşmeleri oluşturmayla ilgili dokümanlar ekledi.
İşe alma önerileri
Projelerden, Dokümanlar Sezonu'na katılmak isteyen diğer projeler için öneride bulunmaları istendi. En çok işe alma önerisi verilenler:
- Teknik yazarlar için işe alım materyallerini programa kabul edilmeden önce bile mümkün olduğunca erken paylaşın. Topluluğunuzdan olası adaylar önermesini isteyin.
- Proje kanallarının dışında geniş bir kitleyle paylaşın. Kapsayıcı bir dil kullanın ve yeterince temsil edilmeyen gruplardan gelen adayların başvurmasını doğrudan teşvik edin.
- Belge oluşturma süreciniz için hangi araçların gerekli olduğunu anlayın ve bu araçları kullanma konusunda deneyimli teknik yazarlar işe alın.
- Teknik yazar için teslimatlar ve aşamalar, iletişim kanalları ve kontrol noktaları, ödeme süreçleri ve zamanlamayla ilgili net beklentiler oluşturun.
- Dokümanlar Sezonu teknik yazar programını kullanarak topluluk üyelerine yatırım yapabilir ve teknik yazar olarak büyümelerine yardımcı olabilirsiniz.
- Teknik yazarları oryantasyona dahil etmek, soruları yanıtlamak ve program sırasında destek sağlamak için beklediğinizden daha fazla zaman ayırın. Özellikle teknik yazarın projenizin alanında daha önce deneyimi yoksa bu süreyi artırın.
- Gelecekteki projelerde kullanmak üzere işe alma, işe yerleştirme ve oryantasyon sürecinizi belgeleyin.
(Not: Teknik yazar adaylarını işe aldıkları tüm projeler, örnek olaylarında belirtilmemiştir.)
Teknik yazarlarla çalışırken karşılaşılan yaygın sorunlar
COVID veya başka hastalıklar ya da pandemiyle ilgili aile sorumlulukları nedeniyle çeşitli projelerdeki teknik yazarların projeden ayrılması gerekti. Bazı projelerde, saat dilimi uyuşmazlığı veya internet bağlantısı sorunlarıyla ilgili iletişim sorunları bildirildi.
Projeler, topluluklarına ilk katılım veya projelerinin doküman araç zincirini ayarlamayla ilgili zorlukları hafife aldıklarını fark etti.
Bazı projelerde, Open Collective ile ilgili bankacılık sorunları veya yazarların ikamet ettikleri ülkelerdeki ödeme kısıtlamaları nedeniyle teknik yazarlara ödeme yapılmasında gecikme yaşandı.
Open Collective ücretleriyle ilgili program dokümanları net değildi: Google, projelere yapılan ilk para transferi için Open Collective işlem ücretlerini karşıladı ancak diğer ödeme kanalları tarafından uygulanan işlem ücretlerini (ör. para birimi dönüştürme ücretleri) karşılamadı. Gelecekteki programların dokümanlarında bu durumu daha net bir şekilde açıklamaya çalışacağız.
Takip anketleri
Belgeler Sezonu programı kapsamında, projelerden takip anketlerine katılmaları istendi. Mayıs, Ağustos ve Kasım 2022'de üç anket gönderildi.
Takip anketinde, projelerin teklif ve örnek olay bağlantılarının hâlâ etkin olduğunu onaylamaları istendi. Anket, projelerin başarıları (örnek olaylarında belirledikleri metriklerle belirlenir) ve proje teknik yazarlarının katılımının devamı ve ücretleri hakkında sorular da içeriyordu:
- Docs Sezonu teknik yazarınızla çalışmaya devam ediyor musunuz?
- Teknik yazarınız hâlâ projeniz üzerinde çalışıyorsa herhangi bir şekilde ücret alıyor mu?
- Bu aşamada doküman projenizin başarılı olduğunu düşünüyor musunuz?
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 şu bilgileri öğrenmeyi umuyoruz:
- Proje alanlarının, doküman türü seçimi veya metrik seçimiyle ilişkili olup olmadığı
- Projenin tamamlanması ve teknik yazarların elde tutulması için en etkili teknik yazar işe alma ve oryantasyon uygulamaları
- Belgelerin etkinliğini ölçmek için makul zaman çizelgeleri
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 belgelemeyle ilgili sorunlarını çözmelerine yardımcı olmaktır.