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.

Ne tür dokümanlar yazıyorsunuz?

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.

Doküman yazarken hangi araçları kullanıyorsunuz?

Hangi profesyonel yazarlık yardımı çözümünü kullanıyorsunuz?

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.

Mevcut çözümünüzden memnun musunuz?

Yazarlık yardımı aracı kullananların %30'u daha iyi alternatifler arıyor.

Teknik yazarlık için profesyonel bir araç kullanmayı düşündünüz mü?

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?

Düşüncelerinizi bizimle paylaşın

Teknik doküman yazmak için hangi işaretleme dilini kullanıyorsunuz?

İç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.

Farklı dokümanlar / kılavuzlar arasında içeriği yeniden kullanıyor musunuz?

Yazım sürecisini hızlandırmak için şablon kullanıyor musunuz?

Ne tür şeyler için şablon yapılandırırsınız?

Parametreleştirilmiş şablonlar (ör. değişkenler içeren şablonlar) oluşturuyor musunuz?

Katılımcıların %69'u daha hızlı yazmak için şablonlardan yararlanmıyor, yararlananların çoğu ise farklı doküman türleri için kullanıyor. Değişkenler içeren dinamik şablonlar için ise kullanan ve kullanmayanların oranı neredeyse eşit.

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.

Teknik dokümantasyon için otomatik kontrolleriniz var mı?

Ne tür kontrollere sahipsiniz?

Dil / stil kontrollerini otomatikleştiriyor musunuz?

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.

API referansları yazıyor musunuz?

İş rolüne göre API referansları yazımı

Koddan otomatik olarak API referansı oluşturuyor musunuz?

%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.

Hangi araçları kullanıyorsunuz?

Otomatik olarak oluşturulan API referanslarını manuel olarak yazılan içerikle genişletmeniz gerekiyor mu?

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.

Dokümantasyon yazdığınız birincil dil nedir?

Dokümantasyonu yerelleştiriyor musunuz?

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.

Teknik Yazarlık:

2023

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.