Teknik Yazarlık
Paylaş:
Bu sorular, yalnızca teknik yazarlık yapan katılımcılara gösterildi.
Tüm katılımcıların %12'si teknik yazarlık yaptığını belirtti. Bunlar arasında, yalnızca %10'u resmî iş unvanı olarak teknik yazarlık rolüne sahip.
Bu bulguya göre, JetBrains'in Geliştirici Ekosisteminin 2023'teki Durumu çalışması kapsamında, doküman yazanların %90'ı kendisini teknik yazar olarak tanımlamıyor; bu da ekipler arasındaki iş birliği, teknik kalite ve tutarlılık ve teknik yazarların rolü hakkında soruları gündeme getiriyor.
Daniele Procida
Mühendislik Direktörü, Canonical
Dokümantasyon yalnızca teknik yazıyla veya yazılanlarla ilgili değildir. Kullanıcının ürünle ilişkisini şekillendirir. Dokümantasyon, yazarlarının da ürünü nasıl anladığını etkiler; bir ürünle ilgilenen herkes aynı zamanda ürün hakkında düşünmeye devam eder.
Alyssa Rock
Topluluk Yöneticisi, The Good Docs Project
Açık olan bir şey var: Geliştiriciler iyi dokümantasyonun değerini görüyorlar (çoğunlukla yetersiz dokümantasyona sahip bir aracı kullanmanın ne kadar can sıkıcı ve zor olacağını biliyorlar). Bununla birlikte, kimi zaman dokümantasyonlarının nasıl iyi hâle getirileceğini bilmiyorlar.
Chris Chinchilla
Yazar ve Podcast Yayıncısı, chrischinchilla.com
Yazar topluluğumuz arasında dil, araçlar ve uygulamalar hakkında sonu gelmeyen çok sayıda tartışma devam ediyor. Ancak bu rakamlar herkesin kaliteli dokümanlar yazmasını kolaylaştıracak araçlara, eğitime ve topluluk tavsiyelerine ihtiyacımız olduğunu gösteriyor.
Katılımcıların çoğu dâhili ve kod dokümantasyonu üzerinde çalışıyor. Geçen yıldan beri, müşteriye yönelik dokümantasyon üzerinde çalışanların oranı yüzde dört puan azaldı.
Dokümantasyon yazma araçları
Özelleştirilebilir metin düzenleyicileri, dokümantasyon yazarlarının tercih ettiği araç olmaya devam ediyor. Metni ve kodu düzenlemek için kullanımı kolay, esnek ve etkili bir araç sunmaları bu düzenleyicileri özellikle belge yazmak için ideal hâle getiriyor.
Ancak bu yıl, özelleştirilebilir metin düzenleyicilerin kullanımında yüzde yedi puanlık bir düşüş görülürken, GitHub sayfalarında neredeyse yüzde altı puanlık eşdeğer bir artış yaşandı. Bu sırada, iş birliğine dayalı wiki dokümantasyonunun önde gelen örneği olan Confluence konumunu koruyor.
Profesyonel yazarlık yardımı çözümü kullanan katılımcıların %3'ünden %42'si özel geliştirilmiş araçları tercih ediyor. Geriye kalan seçenekler arasında öne çıkan tek, daha yeni araç %5'lik payla Paligo. Diğer popüler seçeneklerin tümü geleneksel ve yerleşik araçlar.
Teknik yazıyla ilgilenenlerin yarısından fazlası profesyonel bir araç kullanmayı düşünmemiş olsa da %45 gibi önemli bir oranı bu fikre olumlu bakıyor.
Markup
Markdown önde gelen seçenek olmaya devam ediyor. Ancak geçen yıla kıyasla, standart Markdown (yüzde 7 puan düşüş) ve Markdown türlerinden (yüzde 4 puan düşüş) WYSIWYG ve Office benzeri uygulamalara (yüzde 6 puan artış) doğru görünür bir geçiş var. Bu, kaynaklar üzerindeki kontrolün kolaylık veya kullanıcı dostu olma açısından geri planda kaldığı anlamına mı geliyor?
İçerik yeniden kullanımı ve şablonlar
Katılımcıların neredeyse yarısı içeriği yeniden kullanmak için yapılandırılmış bir yaklaşım kullanıyor. Ancak %32'si, muhtemelen araçlarının sınırlamaları nedeniyle hâlâ kopyalayıp yapıştırıyor; bu da tutarsızlıklara neden olduğu için dokümantasyon sürecini yavaşlatabiliyor.
Otomatik kontroller ve dokümantasyon kalitesi
Katılımcıların yalnızca %13'ü teknik dokümantasyonda otomatik kontroller kullanıyor. Büyük çoğunluk, testler genellikle bozuk işaretleme, bağlantı ve referansları yakalamayı hedeflediği için ortak linter'ler kullanmak yerine şirket içinde test yazmayı tercih ediyor. Dil ve stil kontrolleri için yerleşik yazım denetleyiciler tercih ediliyor.
API dokümantasyonu
Katılımcıların yarısından fazlası API referansları yazıyor. %81'i API referansları yazdığını söyleyen geliştiriciler bu konuda lider konumda. Geliştiricileri, Mimarlar (%19), Teknik Yazarlar (%18) ve DevOps Mühendisleri (%17) gibi roller izliyor. Diğer iş rolleri bu göreve daha az dâhil oluyor ve CIO'lar, CEO'lar ve CTO'lar gibi daha üst düzey pozisyonların küçük bir yüzdesi (%7) API referansı yazıyor.
%61
Çoğunluk (%61), API referanslarını doğrudan koddan otomatik olarak oluşturuyor; bu, verimli dokümantasyon süreçlerinin de göstergesi olan bir uygulama. Araçlar kapsamında, Swagger %84'lük bir payla pazarın hakimi konumunda.
2/3
Otomatikleştirme yapanların yaklaşık üçte ikisi, otomatik olarak oluşturulan içeriklerini hâlâ manuel olarak geliştirme ihtiyacı duyuyor. Otomasyon temel görevleri hızlandırırken, manuel giriş hem bağlam hem de API referanslarına kişisel bir dokunuş eklemek açısından önemlidir.
Diller ve yerelleştirme
İngilizce hâlâ teknoloji dokümantasyonu için en popüler birincil dildir. Çince, bu yıl dört puan kaybederek açık farkla ikinci sırada yer alıyor. Japonca ise geçen yıldan bu yana yüzde yedi puanlık artışla üçüncü sırada.
Katılımcıların yalnızca %14'ü dokümantasyonlarını diğer dillere çeviriyor ve %8'i çevirmeyi düşünüyor. Bu rakamlar geçen yıldan beri önemli ölçüde değişmedi.
Zaman ayırdığınız için teşekkür ederiz!
Raporumuzu faydalı bulduğunuzu umuyoruz. Bu raporu arkadaşlarınızla ve meslektaşlarınızla paylaşın.
Herhangi bir soru ya da öneriniz varsa lütfen bizimle surveys@jetbrains.com adresinden iletişime geçin.