Mevcut aşama:
2021 Dokümanlar Sezonu programı 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 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.
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, çalışmalarından dolayı bulundukları konuma göre burs veren teknik yazarlara danışmaları için mentorlar sağlıyordu. Programda, teknik yazarlar, mentorlar ve kuruluş yöneticilerinin programa katılımlarından memnun olup olmadıkları ölçülmüştür ancak belge sonuçları ölçülmemiştir.
2021 yılında Sezonu Dokümanlar ekibi programda önemli değişiklikler yaparak belge sonuçlarını ölçmeye ve kuruluşlar ile teknik yazarlar için 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 aracılığıyla uygulanmamaktadır, ancak kabul edilen kuruluşlara doğrudan uygulanır
- Kabul edilen kuruluşlar, teknik yazarlara ödeme yapmak için kullandıkları Open Collective üzerinden hibe alıyor
- Teknik yazarlara yönelik ücret kuruluşlar tarafından belirlendi
- Kuruluşlar son değerlendirmeleri ve örnek olayları göndermiş ve takip anketlerini yanıtlamış
2021 yılına ait genel bulgular
Kuruluşlar
- 2021 programında yapılan değişiklikler nedeniyle başvuru yapan kuruluş sayısı azaldı (2021'e kıyasla% 30 daha az sayıda kuruluş başvurdu) ancak 2021 kuruluş yöneticileri, 2020 yöneticilerine kıyasla programdan biraz daha memnun kaldı (%93'e kıyasla %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 eski olduğunu düşünüyordu.
- Projeler genellikle, dokümantasyonun ne kadar etkili olduğunu etkileşimler aracılığıyla ölçmek istediler. Özellikle de daha az sorun yaşanması, dokümanları daha fazla ziyaret edenlerin sayısı ve projelere katılımları oldu.
- Kasım 2022 itibarıyla, 30 projeden 25'inin yanıtladığı görülüyor:
- 18 proje orijinal metriklerini karşıladığını belirtti.
- 5 proje düzeltilmiş metriklerle karşılaştı
- 2 projede, bu sorunun cevabını vermek için henüz çok erken olduğu belirtildi
Programa katılım
- Teknik yazarları işe almak, işe almak ve ücret ödemek, kuruluş yöneticileri için programın en zor kısmıydı.
- Kasım 2022 itibarıyla 30 kuruluştan 24'ü yanıt veriyor:
- 18 kuruluş, Dokümanlar'da Sezonun teknik yazarlarıyla (sürekli katkıda bulunan veya soruları yanıtlayan bir kaynak olarak) çalışmaya devam ediyor
- 4 kuruluş, Sezona ilişkin teknik yazarlarla birlikte ücretli bir görevde çalışıyordu
- 18 kuruluş, Dokümanlar'da Sezonun teknik yazarlarıyla (sürekli katkıda bulunan veya soruları yanıtlayan bir kaynak olarak) çalışmaya devam ediyor
2021'de öne çıkanlar
- Birçok projede, teknik yazarların Dokümanlar Sezonu programı sona erdikten sonra projeleriyle çalışmaya devam etmek istedikleri belirtildi.
- Metanorma'da o kadar çok uzman teknik yazar bulundu ki program süresince Dokümanlar'ın desteklendiği Sezonu'nda birlikte çalışacak yeni bir yazar tutmak için uygun kaynaklar buldular.
- Moja Global, topluluğun dokümantasyon konusunda yoğun ilgi gördüğünü fark etti ve daha fazla 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 82 kuruluş başvurdu ve 30 açık kaynak kuruluşu programa kabul edildi. (Seçim ölçütleri için Uygulamanızı Oluşturma rehberine bakın.) Katılan kuruluşların tam listesini Season of Docs web sitesinde bulabilirsiniz. Kabul edilen 30 kuruluşun tümü, 2021 programına katılımlarını tamamlamak için nihai örnek olay raporlarını gönderdi.
Kuruluşlar hakkında
Dokümanlar 2021 Sezonu'na katılan kuruluşlar, çok çeşitli açık kaynak projeleri temsil etti. 2021 grubunda şunlar yer alıyordu:
- Julia, Perl ve R gibi büyük dil projeleri
- Eğitim, iklim, fintek, sağlık, kütüphane hizmetleri, makine öğrenimi, kütle spektrometrisi, kamu sözleşmeleri ve robot bilimi alanı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 belgeleme araçları için belge projeleri
En büyük alt kategori, Python ekosistemi projeleridir. 2021'de ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite ve SymPy yer alıyordu.
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.
2021 kuruluşlarının belirttiği belge sorunları, hem açık kaynak 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ı:
Kuruluşların birden fazla belge sorunu bildirebileceğini unutmayın. Daha kesin bilgi için her kuruluşla ilgili örnek olayların bağlantılarını içeren Dokümanlar Sezonu 2021 sonuçları sayfasına bakın.
Oluşturulan belge türleri
Eğiticiler, 2021 örnek olaylarında en çok bahsedilen doküman türü oldu.
Örnek olaylarda belirtilen diğer doküman türleri arasında Kod olarak dokümanlar 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ı bulanıktır ve tek bir belgeleme projesi birden fazla belge türü veya özellik içerebilir.
Çeşitli projelerde özel olarak belgeleme türlerinin planlanması için kılavuz olarak Teşhis çerçevesinin kullanımına yer verilmiştir.
Daha kesin bilgi için her kuruluşla ilgili örnek olayların bağlantılarını içeren Dokümanlar Sezonu 2021 sonuçları sayfasına bakı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 etmiş ve almıştır ve diğer üç kuruluş mümkün olan en düşük hibeyi (5.000 ABD doları) talep etmiştir.
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 arasında GitHub yıldızları, Sayfada harcanan 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ı yazma projelerini tamamlama ve örnek olayları gönderme arasındaki kısa zaman nedeniyle 2021 grubunun çoğu, ilk metriklerine ulaşılıp ulaşılmadığını belirlemek için yeterli veri toplayamamıştı.
Daha kesin bilgi için her kuruluşla ilgili örnek olayların bağlantılarını içeren Dokümanlar Sezonu 2021 sonuçları sayfasına bakın.
Teknik yazarlarla çalışma
Dokümanlar Sezonu programında 2021'de 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 ücret alıyordu.
2021'de teknik yazarlar doğrudan projelere başvurdu ve projeler, Dokümanlar Sezonu Open Collective fonu aracılığıyla yapılan ödemelerle teknik yazar maaşları için bütçe belirler.
2021 programına katılan projelerin çoğu, teknik yazar işe alma veya işe alma konusunda çok az deneyime sahipti ya da hiç deneyime sahip değildi. Birçok projede sürecin bu aşaması, daha fazla desteğe ihtiyaç duyulduğunu söylüyordu. Bu geri bildirime yanıt olarak, Dokümanlar Sezonu ekibi, program kılavuzuna teknik yazar sözleşmeleri oluşturmak için 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ının dışında geniş çapta paylaşım yapmak. Kapsayıcı bir dil kullanın ve yeterince temsil edilmeyen gruplardan gelen adayları doğrudan başvuruya teşvik edin.
- Doküman oluşturma süreciniz için hangi araçların gerekli olduğunu anlayın ve bu araçları kullanma deneyimi olan teknik yazarlar işe alın.
- Teknik yazar için teslimatlar ve ara hedefler, iletişim kanalları ve görüşmeler, ödeme süreçleri ve zamanlama hakkında net beklentiler oluşturun.
- Mentorluk ve koçluk sağlamak için Dokümanlar Sezonu teknik yazarlığından yararlanarak topluluk üyelerine yatırım yapabilir ve onların teknik yazarlar olarak kendilerini geliştirmelerine yardımcı olabilirsiniz.
- Özellikle teknik yazarların proje alanında deneyime sahip olmadığı durumlarda, teknik yazarları işe almak, program boyunca soruları yanıtlamak ve destek sağlamak için beklediğinizden daha fazla zaman ayırın.
- Gelecekteki projelerde kullanmak üzere işe alım, işe alım ve ilk katılım sürecinizi belgeleyin.
(Not: Örnek olaylarda teknik yazar adaylarını işe aldıkları tüm projeler belirtilmemektedir.)
Teknik yazarlarla çalışırken sık karşılaşılan sorunlar
Bazı projelerde teknik yazarlar, COVID veya diğer hastalıklar ya da ailelerinin pandemiyle ilgili sorumlulukları nedeniyle işten ayrılmak zorunda kaldı. Bazı projelerde, saat dilimi uyuşmazlıkları veya internet bağlantısı sorunları içeren iletişim sorunları bildirildi.
Projeler, topluluklarına katılmanın veya projelerinin belge araç zincirini oluşturmanın zorluklarını hafife aldığını gördü.
Open Collective'deki bankacılık sorunları veya yazarların bulunduğu ülkelerde ödeme kısıtlamaları olduğu için bazı projelerde teknik yazarlara ödeme yapma konusunda gecikmeler yaşandı.
Open Collective ücretleriyle ilgili program belgeleri açık değildi: Google, projelere yapılan ilk para transferleri için Open Collective işlem ücretlerini karşıladı, ancak diğer bazı ödeme kanalları tarafından uygulanan işlem ücretlerini (para birimi dönüştürme ücretleri gibi) karşılamadı. Gelecek programlarda bu hususu daha net bir şekilde açıklamaya ç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, teklif ve örnek olay bağlantılarının hâlâ etkin olduğunu onaylamaları istenmiştir. Ankette ayrıca projelerinin başarısı (örnek olayda belirlenen metriklerle belirlenen şekilde) ve projede teknik yazarların sürekli katılımı ve maaşları hakkında sorular yer alıyordu:
- Hâlâ Sezonun Dokümanlar hakkında teknik yazar mı çalışıyorsunuz?
- Teknik yazarlarınız hâlâ projenizde çalışıyorsa herhangi bir ücret alıyor musunuz?
- Bu noktada belgeleme projenizin başarılı olduğunu düşünüyor musunuz?
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 şu konular hakkında bilgi edinmeyi umuyoruz:
- Proje alanlarının doküman 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 işe alıştırma uygulamaları
- Belgelerin etkinliğini ölçmek için makul zaman çizelgeleri
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.