Mevcut aşama:
Dokümanlar Sezonu 2021, 14 Aralık 2021'de sona erdi. Zaman çizelgesini inceleyin.
Dokümanlar Sezonu hakkında
Sezon, Google Açık Kaynak Programları Ofisi tarafından yönetilen bir sürdürülebilirlik programıdır. Dokümanlar Sezonu'nun 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ırsatları sunun
- Açık kaynak, belgeleme ve teknik yazım konularında farkındalığı artırın
- Açık kaynak belgelerinde etkili metriklerle ilgili bilgi toplama ve paylaşma
Dokümanlar 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 ve teknik yazarların her biri 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, yaptıkları iş karşılığında bulundukları yere göre ücret alan teknik yazarlara danışmanlar sağladı. Programda; teknik yazarlar, mentorlar ve kuruluş yöneticilerinin programa katılımlarından memnun olup olmadıkları ölçülmüştür ancak belgeleme sonuçları ölçülmemiştir.
2021 yılında Dokümanlar Mevsimi ekibi programda önemli değişiklikler yaparak belge sonuçlarını ölçmeye ve kuruluşlar ile teknik yazarlara daha fazla esneklik sağlamaya odaklandı.
- Bütçe ve önerilen metrikler dahil olmak üzere proje teklifleriyle uygulanan kuruluşlar
- Teknik yazarlar artık kuruluşlarla eşleştirilmek için Google üzerinden değil, kabul edilen kuruluşlara doğrudan uygulanır
- Kabul edilen kuruluşlar, teknik yazarlara ödeme yapmak için kullandıkları Open Collective üzerinden bağış aldı
- Teknik yazarlara yönelik ücret kuruluşlar tarafından belirlendi
- Kuruluşlar nihai değerlendirmeleri ve örnek olayları göndermiş ve takip anketlerini yanıtlamış
2021 genel bulguları
Kuruluşlar
- 2021 programında yapılan değişiklikler nedeniyle başvuru yapan kuruluş sayısı azaldı (2021'e kıyasla 2021'de başvuran kuruluş sayısı% 30 azaldı) ancak 2021'de kuruluş yöneticileri, 2020 yöneticilerine kıyasla programdan biraz daha memnun kaldı (%93-%91)
Sorunlar, doküman türleri ve metrikler
- Çoğu proje, bakım yükünü azaltmak (sorunları/soruları azaltarak) ve/veya projeye katılımı artırmak (proje kullanıcıları ya da katkıda bulunanlar tarafından) için belge oluşturmaya odaklanmıştır.
- 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 belgelerinin eksik, düzensiz veya güncelliğini yitirmiş olduğunu düşünmüştür.
- Projeler genellikle, belgelerin ne kadar etkili olduğunu etkileşimler aracılığıyla ölçmek istediler. Özellikle de daha az sorun yaşanırken belgeleri ve projelere daha fazla ziyaretçi çekmek isteniyordu.
- Kasım 2022 itibarıyla 30 projeden 25'i yanıt veriyor:
- 18 projede orijinal metriklerine ulaştığını söyleyenlerin oranı
- 5 proje revize edilen metriklere ulaştı
- 2 projede, bunun için henüz çok erken olduğu belirtildi
Programa katılım
- Teknik yazar işe alma, işe alma ve ö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 vermiştir:
- 18 kuruluş, Dokümanlar Mevsimi teknik yazarlarıyla çalışmaya devam ediyor (sürekli katkıda bulunan veya soruları yanıtlayan bir kaynak olarak)
- 4 kuruluş, Dokümanlar Mevsimi teknik yazarlarıyla birlikte ücretli bir rol üstleniyordu.
- 18 kuruluş, Dokümanlar Mevsimi teknik yazarlarıyla çalışmaya devam ediyor (sürekli katkıda bulunan veya soruları yanıtlayan bir kaynak olarak)
2021'in öne çıkanları
- Birden fazla projede, teknik yazarların Dokümanlar Sezonu programı sona erdikten sonra projeleriyle çalışmaya devam etmeyi amaçladığı belirtildi.
- Metanorma'da o kadar çok nitelikli teknik yazar başvurdu ve program sırasında Dokümanlar'ın Sezonu tarafından desteklenen yazarlarla birlikte çalışacak yeni bir yazar tutmak için uygun kaynaklar buldular.
- Moja Global, topluluğun belgelere büyük ilgi gösterdiğini fark etti ve daha fazla sayıda katkıda bulunanın proje belgelerine katılmasını sağlamak için yeni bir Belgeleme Çalışma Grubu oluşturdu
2021 özet verileri
2021'de programa 82 kuruluş başvurdu ve 30 açık kaynak kuruluşu kabul edildi. (Seçim ölçütleri için Başvurunuzu Oluşturma kılavuzuna bakın.) Katılımcı kuruluşların tam listesini Dokümanlar Sezonu web sitesinde bulabilirsiniz. Kabul edilen 30 kuruluşun tümü, 2021 programına katılımlarını tamamlamak için nihai örnek olay raporunu gönderdi.
Kuruluşlar hakkında
Dokümanlar Sezonu 2021'e katılan kuruluşlar, çok çeşitli açık kaynak projeleri temsil etti. 2021 kohortunda yer alanlar:
- Julia, Perl ve R gibi büyük dil projeleri
- Eğitim, iklim, fintek, sağlık hizmetleri, kütüphane hizmetleri, makine öğrenimi, kütle spektrometrisi, halka açık sözleşmeler ve robotik alanlarındaki projeler
- Kaos mühendisliği araçları, fuzzer'lar, chatbot SDK'ları, yazılım bileşimi analizi ardışık düzenleri, performans izleme araçları ve görsel programlama araçları dahil olmak üzere geliştirici odaklı projeler
- Redocly ve Metanorma gibi belge araçları için belge projeleri
En büyük alt kategori, Python ekosistemi projeleriydi. 2021'de ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite ve SymPy kullanılmıştır.
Projelerle ilgili meta veri (kurulma tarihi, katkıda bulunanların coğrafi dağılımı, katkıda bulunanların sayısı veya kullanıcı tabanı boyutu gibi) toplamadık.
Projelerden hangi açık kaynak lisansının kullanıldığını belirtmelerini istedik.
2021 kuruluşlarının yürüttüğü belge sorunları, hem açık kaynaklı projelerde hem de genel olarak teknik belgelerde çok sık karşılaşılan sorunlardır.
Kuruluşların 2021 programında çözmeyi umdukları başlıca sorunlar şunlardır:
Kuruluşların birden fazla dokümanla ilgili sorun bildirebileceğini unutmayın. Daha ayrıntılı bilgi için her kuruluşla ilgili örnek olayların tamamını içeren Dokümanlar Sezonu 2021 sonuçlar sayfasına göz atın.
Oluşturulan belge türleri
Eğiticiler, 2021 örnek olaylarında en çok bahsedilen belge türü oldu.
Örnek olaylarda bahsedilen diğer doküman türleri arasında Kod olarak doküman ardışık düzeni, Diagram, Sözlük, Stil Kılavuzu, SSS, Uluslararasılaştırma, Codelab, İçerik modeli, Modüller, Kavram dokümanları, Hata mesajları, Kullanıcı araştırması, Readme, Bilgi Tabanı yer alır.
Bu kategorilerden bazıları belirsizdir ve tek bir belgeleme projesi birden fazla belge türü veya özellik içerebilir.
Çeşitli projelerde belge türlerinin planlanmasında rehber olarak Diátaksi çerçevesi kullanılmıştır.
Daha ayrıntılı bilgi için her kuruluşla ilgili örnek olayların tamamını içeren Dokümanlar Sezonu 2021 sonuçlar sayfasına göz atın.
Bütçe sayısı
2021'de ortalama bütçe talebi 10.200 ABD doları, ortanca değer ise 10.000 ABD dolarıydı. Yalnızca üç kuruluş mümkün olan en yüksek hibeyi (15.000 ABD doları) talep etti ve aldı. Diğer üç kuruluş da mümkün olan en düşük hibeyi (5.000 ABD doları) istedi.
Metrikler
Vaka analizlerinde ana hatlarıyla açıklanan projeler, belgeleme projelerinin başarısını ölçmek için kullandıkları metrikler.
Önerilen başlıca metrikler şunlardı:
Önerilen diğer metrikler arasında GitHub yıldızları, Sayfada geçirilen süre, Posta listesi dönüşümleri, Nitel kullanıcı testi, Forumlardaki katılımcı sayısı, İş ortağı/gönüllü/entegrasyon sayısı yer alıyordu.
Teknik yazı projelerinin tamamlanması ile örnek olayların gönderilmesi arasındaki kısa zaman aralığı nedeniyle 2021 grubunun çoğu ilk metriklerine ulaşılıp ulaşılmadığını belirlemek için yeterli veri toplayamamıştı.
Daha ayrıntılı bilgi için her kuruluşla ilgili örnek olayların tamamını içeren Dokümanlar Sezonu 2021 sonuçlar sayfasına göz atın.
Teknik yazarlarla çalışma
2021 yılında 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şvurdu ve program yöneticileri tarafından projelerle eşleştirildi ve doğrudan Google'dan sabit bir maaş alıyordu.
2021'de teknik yazarlar doğrudan projelere başvurdu ve projeler, Dokümanlar Sezonu Open Collective Fund aracılığıyla yapılan ödemelerle teknik yazar maaşları için bütçe belirledi.
2021 programına katılan projelerin çoğunda teknik yazar işe alma veya işe alma konusunda çok az deneyimli ya da hiç deneyim yoktu. Birçok projede sürecin bu aşaması, daha fazla desteğe ihtiyaç duyulduğunu belirtti. Bu geri bildirimlere yanıt olarak, Dokümanlar Mevsimi ekibi, program kılavuzuna teknik yazar sözleşmeleri oluşturmaya ilişkin belgeler ekledi.
İşe alım önerileri
Projelerden, Dokümanlar Mevsimi'ne katılmak isteyen diğer projeler için önerilerde bulunmaları istendi. En çok işe alım önerileri şunlardı:
- 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ı yönlendirmelerini isteyin.
- Proje kanalları dışında geniş çaplı paylaşımlar yapmak. Kapsayıcı bir dil kullanın ve yeterince temsil edilmeyen gruplardan gelen adayları doğrudan başvurmaya teşvik edin.
- Belge oluşturma süreciniz için hangi araçların gerekli olduğunu öğrenin ve bu araçları kullanma deneyimi olan teknik yazarları işe alın.
- Teknik yazarın teslimatlar ve ara hedefler, iletişim kanalları, görüşmeler, ödeme süreçleri ve zamanlama hakkında net beklentileri olsun.
- Mentorluk ve koçluk sağlamak için Dokümanlar Sezonu teknik yazarı olarak topluluk üyelerine yatırım yapmayı ve onların teknik yazarlar olarak büyümelerine yardımcı olmayı düşünün.
- Özellikle teknik yazarın proje alanında önceden deneyimi yoksa teknik yazarları işe almak, program sırasında soruları yanıtlamak ve destek sağlamak için beklediğinizden daha fazla zaman ayırın.
- Gelecekteki projelerinizde kullanmak üzere işe alım, işe alma ve ilk katılım sürecinizi belgeleyin.
(Not: Örnek olay incelemesinde teknik yazar adaylarını işe aldıkları tüm projeler değil.)
Teknik yazarlarla çalışırken sık karşılaşılan sorunlar
Bazı projelerde çalışan teknik yazarlar, COVID veya diğer hastalıklar ya da pandemiyle ilgili aile sorumlulukları nedeniyle okuldan ayrılmak zorunda kaldı. Bazı projelerde, saat dilimi tutarsızlıkları veya internet bağlantısı sorunları içeren iletişim sorunları bildirildi.
Projeler, topluluklarına ilk katılımın veya projelerinin belge araç zincirinin oluşturulmasındaki zorlukları hafife aldıklarını fark ettiler.
Open Collective ile ilgili bankacılık sorunları veya yazarların ikamet ettiği ülkede ödeme kısıtlamaları nedeniyle bazı projelerde teknik yazarlara ödeme yapma konusunda gecikmeler oldu.
Open Collective ücretleriyle ilgili program belgeleri açık değildi: Google, projelere yapılan ilk para transferleri için Açık Toplu işlem ücretlerini karşıladı, ancak diğer bazı ödeme kanalları tarafından uygulanan işlem ücretlerini (ör. para birimi dönüştürme ücretleri) karşılamadı. Gelecekteki programlarda bu durumu belgelendirerek daha iyi anlaşılmasını sağlamaya çalışacağız.
Takip anketleri
Dokümanlar Sezonu programı kapsamında projelerden takip anketlerine katılmaları istendi. Mayıs, Ağustos ve Kasım 2022'de üç anket gönderildi.
Takip anketinde, projelerden, tekliflerinin ve örnek olay bağlantılarının hâlâ etkin olduğunu onaylamaları istendi. Ankette ayrıca projelerinin başarısı (örnek olayda belirledikleri metriklerle belirlenir) ve projeye teknik yazarların sürekli katılımı ve maaşları hakkında sorular da yer alıyordu:
- Dokümanlar sezonuyla ilgili teknik yazarlarla çalışmaya devam ediyor musunuz?
- Teknik yazarınız hâlâ projenizle çalışıyorsa herhangi bir ücret alıyor mu?
- Bu aşamada belgeleme projenizin başarılı olduğunu düşünüyor musunuz?
Gelecekteki sorular
Her zaman olduğu gibi, açık kaynak belgeleri hakkında ne kadar çok bilgi edinirsek, o kadar çok öğrenmek istiyoruz! Gelecek sezonlarda şu konular hakkında bilgi edinmeyi umuyoruz:
- Proje alanlarının belge türü seçimiyle veya metrik seçimiyle ilişkili olup olmadığı
- Projeyi tamamlama ve teknik yazarları elde tutma açısından en etkili teknik yazar işe alma ve oryantasyon uygulamaları
- Belgelemenin etkinliğini ölçmek için makul takvimler
Öğrenmek istediğimiz pek çok soru olsa da Dokümanlar Dönemi'ne katılan açık kaynak proje yöneticilerinin ve yöneticilerinin zamanına saygı duymak istiyoruz. Bu programın en önemli önceliği, projelerin belgelemeyle ilgili sorunlarını çözmelerinde desteklemektir.