Teknik dokümantasyon yazmak

Merak sorusu

Ödeme servisinin klasöründe tek bir dosya var: "notes.txt". İçinde Türkçe ve İngilizce karışık birkaç satır, bir şifre bilgisi ve "ask Burak" diye biten bir cümle. Burak bir yıl önce şirketten ayrılmış. Berlin'den gelen yeni geliştirici Jonas servisi kendi bilgisayarında çalıştırmak için iki gündür uğraşıyor.

Emre ilk taslağı yazmaya oturuyor ve ilk cümlesi şöyle çıkıyor: "In this document, we will try to explain how the payment service was developed and how it will be used." Cümleyi yeniden okuyunca bir şeyin yanlış olduğunu hissediyor, ama neyin? Jonas'ın ikinci gün değil, ilk saatinde servisi çalıştırabilmesi için bu belge nasıl yazılmalı?

Anlatım

Belgenin okuru bir görev peşinde

Teknik bir belgeyi kimse baştan sona keyifle okumaz. Okur bir şey yapmak ister: servisi kurmak, bir ayarı değiştirmek, bir uç noktayı çağırmak. Bu yüzden iyi bir belge okurun sorularına sırayla cevap verir: bu nedir, nasıl çalıştırırım, nasıl kullanırım, bir şey ters giderse ne yaparım? Bir yazılım projesinin ana belgesi olan README dosyası genellikle bu sorulara göre bölümlenir: kısa bir tanım, gereksinimler, kurulum adımları, ayarlar ve bir kullanım örneği.

İlk cümle servisin ne yaptığını tek cümlede söyler. Emre'nin taslağındaki "In this document, we will try to explain…" cümlesi ise yalnızca belgenin varlığını duyurur ve okura hiçbir şey vermez.

Rehberin dört önerisi

Google'ın geliştirici dokümantasyonu için yayımladığı stil rehberi, teknik İngilizcenin birkaç temel alışkanlığını açıkça önerir. Birincisi, okura doğrudan "you" diye seslenmektir; "we" ve "let's" yerine. İkincisi, etken çatıdır: eylemi kimin yaptığı, okur mu, sunucu mu, kullanıcı mı, açık olmalıdır. Üçüncüsü, genel davranışı şimdiki zamanla anlatmaktır: "The server sends a confirmation", "will send" değil. Dördüncüsü, talimatları emir kipiyle vermek ve bir koşul varsa onu talimattan önce yazmaktır.

Bu dört öneri Emre'nin ilk cümlesindeki her sorunu açıklar: "we" yerine "you", "was developed" yerine etken çatı, "will be used" yerine şimdiki zaman.

Adımlar: numaralı, emir kipiyle, koşul önce

Kurulum gibi sıralı işler numaralı adımlarla yazılır ve her adım bir emir cümlesidir. Emir cümlelerinin yapısını seviye derslerinin başında, Ders EN1.25'te görmüştün; teknik belgede aynı yapı, kısa ve tek eylemli adımlara dönüşür. Bir adım yalnızca belirli bir durumda gerekiyorsa koşul başa gelir, böylece okur adımı yapmadan önce kendisi için geçerli olup olmadığını bilir. İsteğe bağlı bir adım da açıkça işaretlenir.

Sırayı ters çevirmek, "Install the ARM version if you are using a Mac", okurun önce yanlış şeyi kurmasına yol açabilir.

Bir uç noktayı anlatmak

Bir API belgesi her uç nokta için aynı soruları cevaplar: ne yapar, ne ister, ne döner ve hangi hataları verebilir. Tanım bir fiille başlar ve şimdiki zamandadır: "Creates a payment", "Returns the status of a refund". Parametreler adları, türleri ve zorunlu olup olmadıklarıyla verilir. Hata durumları ise ne olduğunu ve okurun ne yapması gerektiğini söyler.

Son cümle Emre'nin önceki gün düzelttiği hatanın belgedeki karşılığıdır: bir sonraki geliştirici aynı hatayı yapmadan önce okur.

Kısa cümle, tek terim

Teknik belgeler çoğu zaman anadili İngilizce olmayan okurlar tarafından okunur ve bazen çeviri araçlarından geçer. Kısa cümleler, tek bir fikir taşıyan paragraflar ve her yerde aynı terimi kullanmak belgeyi bu okurlar için de anlaşılır kılar. Bir bölümde "payment", bir başkasında "transaction", üçüncüsünde "charge" demek, okura bunların üç farklı şey olduğunu düşündürür.

Türkçe köprüsü

Türkçe teknik belgelerde sık görülen "Bu dokümanda … anlatılacaktır" ve "… yapılmalıdır" gibi kalıplar İngilizceye birebir taşındığında edilgen ve geleceğe dönük cümleler üretir: "In this document, … will be explained", "… should be done". Okur bu cümlelerde kimin neyi yapacağını aramak zorunda kalır. İngilizce belgede aynı bilgi okura doğrudan söylenir: "This guide shows you how to…", "Run…".

Bir alışkanlık daha var: Türkçede emir kipi, özellikle yazıda, bazen kaba ya da fazla doğrudan hissettirebilir ve yazarlar onu "yapınız", "yapılması rica olunur" gibi biçimlerle yumuşatır. Teknik İngilizcede emir kipi kaba değildir; okura zaman kazandıran, beklenen biçimdir. "Please" sözcüğü de çoğu adımda gereksizdir; bir rehberin her satırı zaten bir ricadır.

Gerçek hayattan örnekler

Emre README'yi baştan yazıyor. Tek cümlelik bir tanım, üç maddelik gereksinim listesi, altı numaralı kurulum adımı, bir ayar tablosu yerine her ayarı bir cümleyle anlatan kısa bir liste ve bir kullanım örneği. "notes.txt" içindeki şifre bilgisini belgeden çıkarıp ekibin parola yöneticisine taşıyor. Sonra Jonas'tan belgeyi hiçbir şey sormadan izlemesini istiyor.

Jonas yirmi dakika sonra mesaj atıyor: servis çalışıyor, ama dördüncü adımda bir ortam değişkeninin adı eksik. Emre adımı düzeltiyor. Lena belgeyi okuyup ekibin sohbet kanalına bir bağlantı bırakıyor: "New README for payments. Read this before you ask Emre." Emre gülüyor; ilk kez biri ona soru sormadan bir şeyi çalıştırmış.

Sık yapılan hata

Bir başka sık sorun, aynı şey için farklı terimler kullanmaktır. Bir kavram için bir terim seç ve belgenin sonuna kadar onu kullan.

Mini alıştırma

1. İyi bir README okurun hangi sorularına sırayla cevap verir?
2. Google'ın rehberine göre okura nasıl seslenilir?
3. Genel davranışı anlatırken hangi zaman önerilir?
4. Bir koşul ile bir talimat aynı cümledeyse hangisi önce gelir ve neden?
5. Bir uç nokta açıklaması hangi dört soruyu cevaplar?

Cevaplar

1. Bu nedir, nasıl çalıştırırım, nasıl kullanırım, bir şey ters giderse ne yaparım.
2. You ile, doğrudan; we ve let's yerine.
3. Şimdiki zaman: The server sends…, will send değil.
4. Koşul önce gelir; okur adımı yapmadan önce kendisi için geçerli olup olmadığını bilir.
5. Ne yapar, ne ister, ne döner ve hangi hataları verebilir.

Sesli tekrar görevi

Ardından Emre'nin ilk cümlesini sesli düzelt: "In this document, we will try to explain…" yerine "This guide shows you how to…". İki cümleyi art arda söyleyip farkı dinle.

Özet kartı

1. Belgenin okuru bir görev peşindedir: bu ne, nasıl çalıştırırım, nasıl kullanırım, sorun olursa ne yaparım.
2. İlk cümle servisin ne yaptığını söyler; belgeyi duyurmaz.
3. Google rehberi: you, etken çatı, genel davranış için şimdiki zaman, emir kipi.
4. Adımlar numaralı ve tek eylemli; koşul talimattan önce; Optional: ile isteğe bağlı adım.
5. Uç nokta: ne yapar, ne ister, ne döner, hangi hatalar.
6. Kısa cümle, tek fikir, bir kavrama tek terim.

Sonraki derse köprü

Jonas'ın da katıldığı ekip artık her sabah on beş dakikalık bir toplantıyla güne başlıyor ve iki haftada bir sprintin sonunu birlikte değerlendiriyor. Emre ilk sprint değerlendirmesinde ne söyleyeceğini, bir işin gecikeceğini nasıl duyuracağını ve bir geçmiş değerlendirmesinde ekibe nasıl öneri getireceğini düşünüyor. Stand-up ve sprint toplantılarının dili sıradaki ders.