Örneklerle Teknik Dokümantasyon Nasıl Yazılır

Teknik dokümanları, ürünü oluşturan kişiler ile ürünü kullananlar arasındaki el sıkışma olarak düşünebilirsiniz. İster API kılavuzları, ister kullanıcı kılavuzları veya yeni ekip üyeleri için işe başlama talimatları yazıyor olun, her şeyi açık ve basit tutmak ilgili herkesin hayatını çok daha kolaylaştırır. Kimse sadece işini halletmek isterken kafa karıştırıcı veya eksik dokümanlar arasında boğulmak istemez. Günümüzde iyi dokümantasyon sadece 'olsa iyi olur' değil, ürününüzün gerçekten kullanılıp sevilmesini istiyorsanız temel bir 'olmazsa olmaz'dır.

Bu kılavuzda, profesyonel bir yazar olmasanız bile mükemmel teknik dokümantasyon yazmak için ihtiyacınız olan her şeyi ele alacağız. Başlamanıza yardımcı olacak örnekler ve şablonlar da göstereceğiz.

Teknik Dokümantasyon Neden Önemlidir?

Teknik dokümantasyon birden çok kitleye hizmet eder — geliştiriciler, tasarımcılar, test uzmanları, kullanıcılar, paydaşlar — ve bir dizi işlevi yerine getirir:

• Kullanıcılara kurulum, özellikler ve sorun giderme konularında rehberlik eder.
• Dahili ekiplerin ürün detayları konusunda uyumlu kalmasına yardımcı olur.
• İşe başlama hızını artırır ve destek taleplerini azaltır.
• Yazılım ve donanım sistemleri için yaşayan bir bilgi tabanı görevi görür.

İyi belgelenmiş bir proje sadece kullanıcılara yardımcı olmakla kalmaz, aynı zamanda katkıda bulunanları da çeker. Aslında, GitHub verileri, net ve kapsamlı dokümantasyona sahip projelerin geliştirici topluluğundan önemli ölçüde daha fazla etkileşim ve çekme talebi (pull request) aldığını göstermektedir.

Teknik Dokümantasyon Türleri

Kitleye ve kullanım durumuna bağlı olarak farklı teknik dokümantasyon biçimleri vardır:

1. API Dokümantasyonu

Geliştiriciler tarafından API'lerle nasıl entegre olacaklarını ve etkileşim kuracaklarını anlamak için kullanılır. Bu dokümanlar uç noktaları (endpoints), parametreleri, yanıt formatlarını, durum kodlarını, örnekleri ve kullanım notlarını içerir.

Örnek: Stripe API dokümantasyonu, ödemeler için uç noktaları, örnek JSON ile yanıtları ve birden çok dilde gerçek zamanlı kod örneklerini sergiler.

2. Kullanıcı Kılavuzları

Son kullanıcılar tarafından yazılım veya donanım ürünlerini nasıl çalıştıracaklarını anlamak için kullanılır. Bunlar basılı, dijital veya ürüne gömülü olabilir.

Örnek: Bir masaüstü uygulaması, arayüzde nasıl gezineceğini açıklayan, ilk kez kullananlar için yerleşik bir yardım kılavuzu içerebilir.

3. Geliştirici Kılavuzları

Bu dokümanlar, mühendislerin sistemin dahili olarak nasıl çalıştığını anlamalarına yardımcı olmak için kurulum, yapılandırma ve mimariyi açıklar.

Örnek: Yeni geliştiriciler için depo yapısı, CI/CD süreçleri ve yaygın geliştirme iş akışlarını içeren işe başlama dokümanları.

4. Sistem Mimari Dokümanları

Bunlar, farklı sistemlerin nasıl etkileşim kurduğunu özetleyen dahili dokümanlardır. Diyagramlar, protokoller ve üçüncü taraf hizmet detaylarını içerirler.

Örnek: Mikro hizmetlerin Kafka üzerinden nasıl iletişim kurduğunu ve her bir parçanın hangi ekibe ait olduğunu gösteren bir doküman.

5. Sürüm Notları ve Değişiklik Günlükleri (Changelogs)

Her sürümde yayınlanan güncellemelerin, düzeltmelerin ve özelliklerin kısa açıklamaları. Bunlar kullanıcılar ve dahili QA ekipleri için çok önemlidir.

Örnek: “Sürüm 1.2.3 – Karanlık mod eklendi, Safari'deki oturum açma sorunu düzeltildi ve v1/login uç noktası kullanımdan kaldırıldı.”

Harika Teknik Dokümantasyon Nasıl Yazılır?

Açıklık ve kullanılabilirlik sağlamak için şu adımları izleyin:

1. Kitleyi Anlayın

Herhangi bir şey yazmadan önce, kimin için yazdığınızı belirleyin. Geliştiriciler mi? Son kullanıcılar mı? Teknik olmayan paydaşlar mı? Tonu ve yapıyı kitleye göre uyarlamak etkinliği artırır.

Yapın:

• Geliştiriciler için kesin terminoloji kullanın.
• Teknik olmayan kullanıcılar için sade bir dil kullanın.

Yapmayın:

• Dokümanları açıklama yapmadan jargonla aşırı yüklemeyin.

2. Kapsamı ve Hedefleri Belirleyin

Okuyucu dokümanınızı okuduktan sonra ne yapabilmelidir? Bir özelliği mi açıklıyorsunuz yoksa bir entegrasyonu mu adım adım anlatıyorsunuz?

Örnek: “Bu kılavuzun sonunda, OAuth2 kullanarak kullanıcıların kimliğini nasıl doğrulayacağınızı bileceksiniz.”

3. Yazmadan Önce Taslak Oluşturun

Basit bir taslakla başlayın. Bunu bölümlere ayırın:

• Giriş / Genel Bakış
• Önkoşullar
• Kurulum / Yükleme
• Kullanım / Örnekler
• Sorun Giderme / SSS

Bu, yapıyı korumanıza ve içeriği tekrarlamaktan kaçınmanıza yardımcı olur.

4. Açık ve Kısa Yazın

Basit, özlü bir dil kullanın. Uzun paragraflardan kaçının. Karmaşık fikirleri madde işaretlerine veya adımlara ayırın.

İpucu: Projeden 6 ay uzak kaldıktan sonra gelecekteki kendinize açıklıyormuş gibi yazın.

5. Örnekler ve Kullanım Durumları Ekleyin

Sadece tarif etmeyin - gösterin. Kopyalanabilir kod, ekran görüntüleri ve gerçek dünya senaryoları ekleyin.

Örnek:

curl -X POST <https://api.example.com/v1/user> \\
  -H 'Authorization: Bearer <token>' \\
  -d '{"name": "Jane Doe"}'

6. Tutarlı Biçimlendirme Kullanın

Tutarlı başlıklar, yazı tipleri, kod bloğu stilleri ve bağlantı davranışları kullanın. Markdown veya Mintlify veya ReadMe gibi doküman platformları bunu sağlamaya yardımcı olabilir.

Araç ipucu: Stil kılavuzlarını uygulamak için Vale gibi lint araçları kullanın.

7. Her Şeyi Test Edin

Yeni bir kullanıcı gibi dokümantasyonunuzu takip edin. Komutların, bağlantıların ve kod örneklerinin gerçekten çalıştığını doğrulayın.

Yapmayın: Tüm komutları test etmeden yayınlamayın.

8. Sorun Giderme Bölümleri Ekleyin

Okuyucuların destekle iletişime geçmeden yaygın sorunları çözmelerine yardımcı olun.

Örnek:

Sorun: 401 Yetkilendirilmemiş hatası alınıyor.

ÇözümBearer

Teknik Dokümantasyonda Yaygın Hatalar (örneklerle)

Güncel Olmayan İçerik:

Örnek:

# BUNU YAPMAYIN: Eski API uç noktası
POST /v1/login

Bunun yerine, güncelleyin:

POST /v2/auth/login

Çok Fazla Jargon:

Şunun yerine:

"OAuth 2.0 kullanarak örtülü yetkilendirme akışıyla kullanıcıların kimliğini doğrulayın."

Şöyle yazın:

"Kullanıcıların mevcut hesaplarını (Google veya Facebook gibi) kullanarak oturum açmalarına izin vererek kimliklerini doğrulayın. Bu, parolaları paylaşmadan erişime izin vermenin güvenli bir yolu olan OAuth 2.0'ı kullanır."

Örnek Yok:

Kod parçacıkları ekleyin:

curl -X POST <https://api.example.com/login> \\
     -H "Content-Type: application/json" \\
     -d '{"email": "user@example.com", "password": "mypassword"}'

Dağınık Biçimlendirme:

Metni ayırmak için madde işaretleri, başlıklar ve kod blokları kullanın.

Kullanıcı Geri Bildirimini Yoksaymak:

Bir geri bildirim bölümü veya bağlantısı ekleyin:

“Bir yazım hatası buldunuz veya bir iyileştirme önermek mi istiyorsunuz? Geri bildiriminizi buradan gönderin”

Teknik Dokümanlar İçin En İyi Uygulamalar

Araçlarınızı Bilin

Sürüm oluşturma, geri bildirim ve canlı önizlemeleri destekleyen dokümantasyon platformları kullanın. Popüler seçenekler şunlardır:

• ReadMe: İnteraktif geliştirici merkezleri için.
• Mintlify: AI yardımıyla Markdown tabanlı, Notion tarzı dokümanlar.
• Apidog: API öncelikli dokümantasyon ve test için.

Diyagramlar ve Görseller Kullanın

Bazen tek bir diyagram, bir sayfa metinden daha fazlasını açıklar.

Güncel Tutun

Güncel olmayan dokümantasyon, hiç dokümantasyon olmamasından daha kötüdür. Güncellemeleri sürüm döngünüzün bir parçası yapın.

Dokümanlarınızı Sürümlendirin

Değişen API'ler veya sistemler için, değişiklikleri sürüme göre belgeleyin. Apidog veya Bump gibi araçlar bunu otomatikleştirmeye yardımcı olur.

Dokümanlar İçin İşbirliği ve İş Akışı İpuçları (örneklerle)

Sürüm Kontrolü:

Dokümanlar için GitHub kullanın:

git clone <https://github.com/yourproject/docs.git>
git checkout -b feature/update-auth-docs
# Düzenlemeleri yapın, commit edin ve inceleme için bir çekme talebi (pull request) oluşturun

Akran İncelemeleri:

İnceleyenler için bir kontrol listesi ekleyin:

• Bilgi doğru mu?
• Örnekler çalışıyor mu?
• Dil açık mı?

Düzenli Güncellemeler:

Proje yönetim aracınıza bu hatırlatıcıyı ekleyin:

“v1.3 sürümü için doküman güncellemesi gerekiyor.”

Dokümanları Geliştirme İle Entegre Edin:

Kod değiştiğinde doküman güncellemeleri için uyarı veren sorun şablonları (issue templates) kullanın:

### Bu PR dokümantasyon güncellemesi gerektiriyor mu?
- [ ] Evet
- [ ] Hayır

Daha Fazla Örnek: Hata Mesajları ve Sorun Giderme

Hatayı Açıklayın:

### Hata: 401 Yetkilendirilmemiş
Bu hata, API tokenınızın eksik veya geçersiz olması durumunda oluşur.

Çözümler Sunun:

### Çözüm
1. API tokenınızın süresinin dolup dolmadığını kontrol edin.
2. Tokenı istek başlıklarınıza şu şekilde ekleyin:
   `Authorization: Bearer SİZİN_TOKENINIZ_BURAYA`

Adım Adım Kılavuz:

### 401 Hatası Sorun Giderme
1. Tokenınızın doğru kopyalandığını doğrulayın.
2. Tokenınızın süresinin dolmadığını onaylayın (tokenlar 24 saat geçerlidir).
3. İsteğinizin şu başlığı içerdiğinden emin olun:
   `Authorization: Bearer SİZİN_TOKENINIZ`
4. İsteği yeniden deneyin.

Gerçek Dünya Örneği: Bir OpenAPI Spesifikasyonunu Belgeleme

Diyelim ki temel bir kimlik doğrulama sistemi için üç uç noktası (endpoint) olan bir RESTful API oluşturdunuz: /login, /register ve /getUser. Aşağıda, harika dokümantasyonun nasıl görünebileceğine dair genişletilmiş ve geliştirici dostu bir parça bulunmaktadır.

🔹 Uç Nokta: POST /login

Açıklama: Kullanıcının kimliğini e-posta ve parola kullanarak doğrular. Başarılı olursa bir JWT tokenı döndürür.

İstek Başlıkları:

Content-Type: application/json

İstek Gövdesi:

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Başarılı Yanıt:

• Durum: 200 OK
• Gövde:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Hata Yanıtları:

• 400 Bad Request: Eksik veya geçersiz alanlar
• 401 Unauthorized: Yanlış e-posta veya parola

Örnek cURL İsteği:

curl -X POST <https://api.example.com/login> \\
  -H "Content-Type: application/json" \\
  -d '{"email": "user@example.com", "password": "securePassword123"}'

🔹 Uç Nokta: POST /register

Açıklama: Sisteme yeni bir kullanıcı kaydeder.

İstek Gövdesi:

{
  "email": "newuser@example.com",
  "password": "newUserPassword",
  "confirm_password": "newUserPassword"
}

Yanıt:

• 201 Created:

{
  "message": "User registered successfully.",
  "user_id": "12345"
}

Hatalar:

• 400 Bad Request: Parolalar eşleşmiyor, e-posta zaten mevcut

Örnek cURL İsteği:

curl -X POST <https://api.example.com/register> \\
  -H "Content-Type: application/json" \\
  -d '{"email": "newuser@example.com", "password": "newUserPassword", "confirm_password": "newUserPassword"}'

🔹 Uç Nokta: GET /getUser

Açıklama: Kimlik doğrulama tokenını kullanarak mevcut kullanıcının profilini alır.

Başlıklar:

Authorization: Bearer <sizin_tokeniniz_buraya>

Yanıt:

{
  "id": "12345",
  "email": "user@example.com",
  "created_at": "2025-06-01T12:34:56Z"
}

Hatalar:

• 401 Unauthorized: Eksik veya geçersiz token
• 404 Not Found: Kullanıcı mevcut değil

Örnek cURL İsteği:

curl -X GET <https://api.example.com/getUser> \\
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Teknik Doküman Yazma ve Barındırma Araçları

• Apidog – API öncelikli dokümantasyon ve test tek bir platformda.
• Notion veya Confluence – Dahili dokümantasyon için harika.
• MkDocs veya Docusaurus – Geliştirici odaklı, Git ile entegre dokümanlar için ideal.
• ReadMe veya Mintlify – Analiz ve özelleştirme özellikli harici geliştirici merkezleri.

Sonuç

Mükemmel teknik dokümantasyon yazmak hem bir sanat hem de bir bilimdir. Kitlenizi anlayarak, yapılandırılmış bir süreci takip ederek ve gerçek dünya örnekleri kullanarak, sadece kullanıcılarınızı desteklemekle kalmayıp ürününüzü de geliştiren dokümantasyon oluşturabilirsiniz.

Açık dokümanlar sürtünmeyi azaltır, güven oluşturur ve işbirliğini geliştirir. İster geliştirici, ister ürün yöneticisi veya teknik yazar olun, doküman yazmaya zaman ayırmak size fayda sağlayacaktır.