Dokümantasyon Yazımı
Teknik döküman hazırlarken dikkat edilmesi gereken dil bilgisi ve format kurallarını öğretir. İngilizce teknik dokümantasyon, bir yazılım projesinin başarısı için kod kadar önemlidir; çünkü doğru yazılmış bir kılavuz, ekipler arası iletişimi hızlandırır ve destek taleplerini azaltır.
- README Proje genel bakışı ve kurulum talimatları için başlangıç noktası
- CHANGELOG Sürüm değişikliklerini kayıt altına alan zaman çizelgesi
- API Reference Uç noktalar, parametreler ve dönüş değerleri için yapısal başvuru
- Runbook Operasyonel görevler ve olay müdahale prosedürleri
Dokümantasyon Türleri ve Amaçları
Her belge türü farklı bir okuyucu kitlesine ve kullanım senaryosuna hitap eder.
Bir projeyi ilk kez inceleyen geliştiricinin karşılaştığı ilk belgedir. Projenin ne yaptığı, nasıl kurulduğu, hangi bağımlılıklara sahip olduğu ve nasıl katkıda bulunulacağı gibi temel bilgileri içerir. Sade bir İngilizceyle yazılır; karmaşık terimler ilk geçişte açıkça tanımlanır.
Geliştiricilerin sistemin uç noktalarını, istek-parametrelerini ve dönüş değerlerini hızla bulup uygulamasını sağlar. Standartlaştırılmış bir yapı izler: her uç nokta için HTTP yöntemi, URL, parametre tablosu, örnek istek ve örnek yanıt bölümleri bulunur.
Sistemde yaşanabilecek olağandışı durumlar için adım adım müdahale talimatları verir. Örneğin bir servis yanıt vermediğinde ilk olarak hangi log dosyasının inceleneceği, hangi portun kontrol edileceği ve servisin nasıl yeniden başlatılacağı sıralı madde olarak yazılır.
Bir mimari seçimin neden yapıldığını, hangi alternatiflerin değerlendirildiğini ve hangi kısıtlamaların etkili olduğunu belgeler. Gelecekteki ekip üyelerinin bir tasarım kararının gerekçesini anlaması için yazılır; tartışmayı değil sonucu kaydeder.
Belirsiz Zamirlerden Kaçınma
"The system processes it and sends it to the service" cümlesindeki "it" zamiri okuyucunun hangi nesnenin gönderildiğini tahmin etmesine neden olur. Belge bağlamında bu tür belirsizlikler yanlış yapılandırmaya yol açar.
The gateway processes the request and forwards the payload to the authentication service.
Aktif Çatı ve Emir Kipinin Etkisi
Pasif çatı "The file is uploaded by the client" belgeyi yavaşlatır ve özneyi gizler. Aktif çatı ise hem daha kısa hem daha nettir. Dokümantasyonda her zaman eylemi gerçekleştiren tarafı açıkça belirtin.
Upload the file to the staging directory before running the validation step.
Yaygın Hata: Eylemsiz Cümleler
The configuration should be updated. The data is then processed. It is recommended to restart. The error might be caused by the timeout.
Bu cümleler eylemi gerçekleştiren tarafı ve sıralamayı gizler. Okuyucu "kim güncelliyor, neyle işleniyor, kim öneriyor" sorularını cevapsız bırakır.
Düzeltme: Aktif ve Sıralı
Update the configuration file before deployment. The pipeline processes the data in three stages. Restart the service after each configuration change. Increase the timeout threshold to 60 seconds to resolve the error.
Her cümle bir eylem, bir fail ve bir nesne içerir. Okuyucu adımları sırayla takip edebilir ve hatasız uygulayabilir.
Kural: bir eylemi açıklayan her cümle, okuyucunun kopyalayıp uygulayabileceği bir talimat içermelidir.
İlgili terimleri inceleTeknik İçerikte Yapısal Düzen
İyi bir teknik doküman, okuyucunun ihtiyaç duyduğu bilgiye en az geçişle ulaşmasını sağlar. Yapısal düzen, okuyucunun kılavuzu baştan sona okumasını değil, gerektiğinde yalnızca bir bölümü bulup uygulamasını hedefler.
Tutarlı Başlık Hiyerarşisi
Bir H2 bölümünün altındaki tüm alt başlıklar H3 olmalıdır; H4 atlamayın. Okuyucu hiyerarşiyi takip ederek ilgili bölüme kısa yoldan ulaşır.
Kod ve Metin Ayrımı
Komutları, dosya adlarını ve değişkenleri gövde metninden ayrı biçimlendirin. Okuyucu metinle kodu ayırt edebilmeli; kopyalanabilir alanlar işaretli olmalıdır.
Önkoşul ve Sonuç Bildirimi
Bir adıma geçmeden önce okuyucunun hangi araçları kurmuş olması, hangi izinlere sahip olması ve hangi dosyalara erişmesi gerektiğini açıkça yazın.
Önemli Uyarı İşaretleme
Önkoşullar ve sonuçlar görüntü olarak değil içerik olarak işaretlenmeli. Uyarı etiketleri, okuyucunun dikkat edeceği içeriği tarayıcı olarak ayırt etmesini sağlar.
Okuyucu Profiline Göre Dil Seviyesi
Aynı kavramı açıklayan iki belge, okuyucu profiline göre farklı bir derinlikte yazılır. Hedef kitleye göre dil seviyesini ayarlamak, dokümantasyonun işe yararlığını belirleyen en önemli faktörlerden biridir.
İş etkilerine ve maliyet çıkarımlarına odaklanır. Teknik adımları atlar; bunun yerine hangi sorunun çözüldüğünü, hangi riskin azaltıldığını ve hangi operasyonel kazanım sağlandığını iki-üç paragrafta özetler.
Kod örnekleri, mimari diyagramlar ve yapılandırma dosyalarına doğrudan başvurular içerir. Okuyucu bir sistem mühendisi olduğu için "load balancer" veya "connection pool" gibi terimleri açıklamadan kullanabilir.
Arayüz terimleri ve görsel işaretlerle yazılır. "Settings paneline gidin" gibi ifadeler "yapılandırma dosyasını düzenleyin" ifadesine tercih edilir. Teknik jargon minimumda tutulur.
Yapılandırılmış Bir Operasyon Adımı
- SSH access to the production application server
- Membership in the
opsgroup - Active VPN connection
-
1.
SSH into the application server:
ssh ops@app-prod-01 -
2.
Verify the current status of the service:
systemctl status auth-service -
3.
Restart the service:
sudo systemctl restart auth-service -
4.
Confirm the service is active:
systemctl is-active auth-serviceshould returnactive.
If the service fails to start, revert to the previous configuration file located at /etc/auth/config.bak and contact the infrastructure team.
Tutarlı Yazım ve Terminoloji
İngilizce teknik terimlerin yazımında tutarlılık, okuyucunun kavramları tanımasına yardımcı olur. "database" ve "Database" karışımı, "backend" ile "back-end" ayrımı belirsizlik yaratır.
Bir proje içinde bir terim biçimi seçilmişse, belgenin tamamında o biçim korunmalıdır.
Kısaltma ve Simgeler
İlk geçişte "Application Programming Interface (API)" biçiminde tanımlayın; sonraki geçişlerde yalnızca "API" kullanın. Okuyucu kavramı tanıdıktan sonra tam adı tekrar etmek belgeyi yavaşlatır.
Kısaltmaların açılımı belgenin başında bir terimler tablosuyla da toplanabilir.
Dokümantasyon Gözden Geçirme Kontrol Listesi
Bir teknik dokümanı yayınlamadan önce aşağıdaki maddeleri sırasıyla doğrulayın. Bu adımlar, belgenin hem teknik doğruluğunu hem de okunabilirliğini garantiye alır.
Contact- Her adımın bir eylem fiili içerdiğinden emin olun.
- Önkoşullar adımlardan önce ve eksiksiz listelensin.
- Kod örnekleri kopyalanabilir ve çalıştırılabilir olsun.
- Hata durumları ve geri alma adımları belirlensin.
- Terminoloji belgenin tamamında tutarlı kullanılsın.
- Başlık hiyerarşisinde atlama olmasın.
- Kısaltmalar ilk geçişte tanımlansın.
- Hedef okuyucu profili belirlensin ve dile yansıtılsın.