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?

87%

Şirket içi belgeler

63%

Kod dokümanları

53%

Müşteriye yönelik dokümanlar

1%

Diğer

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?

46%

39%

Özelleştirilebilir bir metin düzenleyici

49%

32%

Confluence veya başka wiki platformu

28%

30%

Bir Office uygulaması

24%

23%

Google Docs

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

42%

Özel çözüm

29%

Adobe FrameMaker

22%

Yardım ve Kılavuz

9%

Adobe RoboHelp

7%

ClickHelp

7%

MadCap Flare

5%

AuthorIt

5%

Paligo

10%

Diğer

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?

77%

70%

Markdown

18%

24%

Emin değilim / WYSIWYG düzenleyici veya Office benzeri bir uygulama kullanıyorum

13%

9%

Özel bir Markdown değişkeni

5%

6%

XML / DITA / DocBook vb.

5%

5%

AsciiDoc

4%

4%

reStructuredText

4%

3%

Diğer

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

47%

Evet, yeniden kullanılabilecek içerikleri kod parçacıklarında saklayarak farklı belgelerden onlara referans veriyorum

32%

Hayır. Araçlarım, içeriği yeniden kullanmayı desteklemediği için benzer içerikleri kopyalayıp yapıştırıyorum

21%

Hayır, aynı içeriği yeniden kullanma ihtiyacım olmuyor

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?

78%

Farklı konu/doküman türleri

48%

Uyarı blokları gibi tekrarlayan içerikler

29%

Karmaşık Markup elementleri

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?

61%

Bozuk işaretleme

56%

Bozuk harici bağlantılar

53%

Eksik kaynaklar

52%

Bozuk dahili referanslar

47%

Bozuk belge yapısı

38%

Bozuk kod örnekleri

6%

Diğer

Dil / stil kontrollerini otomatikleştiriyor musunuz?

54%

Evet, düzenleyicimde yerleşik yazım/dilbilgisi denetimcisi var

22%

Hayır, incelemelere güveniyoruz

13%

Harici bir hizmet kullanıyorum

12%

Otomatik dil denetim araçlarımız var

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ı

81%

68%

Yazılım Geliştirici / Programcı / Yazılım Mühendisi

19%

11%

Mimari

18%

14%

Teknik Yazar

17%

13%

DevOps Mühendisi / Altyapı Geliştiricisi

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?

84%

Swagger

9%

ReDoc

15%

Diğer

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?

62%

İngilizce

18%

Çince

13%

Japonca

2%

Fransızca

1%

İspanyolca

1%

Korece

1%

Almanca

2%

Diğer

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.