Dokümantasyon, yazılım projelerinde en çok ertelenen ve proje sahibi değiştiğinde en çok aranan şeydir. Yüzlerce sayfalık, kimsenin okumadığı belgeler yerine; kısa, güncel ve doğru yerde duran birkaç belge çok daha değerlidir.
Hangi belgeler gerçekten işe yarar?
| Belge | Kime hitap eder? | Soru |
|---|---|---|
| README | Projeye yeni gelen herkes | Bu nedir, nasıl çalıştırırım? |
| Kurulum ve dağıtım rehberi | Bakım yapan kişi | Canlıya nasıl alınır, nasıl geri alınır? |
| Mimari karar kayıtları (ADR) | Gelecekteki geliştiriciler | Neden böyle yapıldı? |
| API dokümantasyonu | Entegrasyon yapanlar | Hangi uç nokta ne yapar? |
| Kullanıcı kılavuzu | Son kullanıcı | Bu işlemi nasıl yaparım? |
İyi bir README
Bir geliştirici README'yi okuyup on beş dakika içinde projeyi kendi bilgisayarında çalıştırabilmelidir:
- Projenin tek paragraflık özeti
- Gereksinimler (ör. .NET 10 SDK, SQL Server)
- Adım adım kurulum ve çalıştırma
- Yapılandırma ayarları ve gizli bilgilerin nereden alınacağı (yapılandırma rehberi)
- Testlerin nasıl çalıştırılacağı
- Klasör yapısının kısa açıklaması
- Sorumlu kişi ve iletişim
Mimari karar kayıtları (ADR)
Kodda bir şeyin ne yapıldığı görülür; neden yapıldığı ise çoğu zaman kaybolur. ADR, önemli teknik kararların kısa kaydıdır:
# ADR-007: Raporlama için ayrı okuma veritabanı
Tarih: 2026-10-05
Durum: Kabul edildi
## Bağlam
Ay sonu raporları canlı veritabanını yavaşlatıyor.
## Karar
Gece çalışan bir aktarım ile raporlar ayrı bir veritabanından okunacak.
## Sonuçlar
Raporlar bir gün gecikmeli olacak; canlı sistem etkilenmeyecek.Her ADR bir iki sayfayı geçmez, kodla birlikte depoda tutulur ve değiştirilmez; karar değişirse yeni bir ADR yazılır. Böylece iki yıl sonra "bunu neden böyle yapmışız?" sorusunun cevabı hazırdır. Bu kayıtlar teknik borç yönetiminde de değerli bir kaynaktır.
API dokümantasyonu
API dokümantasyonunu elle yazmak yerine koddan üretmek, belgeyle kodun ayrışmasını önler. .NET'te bu iş OpenAPI ve Swagger ile yapılır.
Dokümanı güncel tutmak
- Kodun yanında tutun. Belgeyi ayrı bir wikide değil, depoda markdown olarak tutmak güncellenme şansını artırır.
- Değişiklikle birlikte güncelleyin. Kurulum adımını değiştiren bir pull request, README'yi de güncellemelidir.
- Az ama doğru yazın. Kodun zaten açıkça söylediğini tekrar etmeyin.
- Yeni gelenle test edin. Ekibe katılan kişi README ile kurulum yaparken takıldığı yerleri düzeltsin.
İşletmeler için not
Bir yazılım projesi teslim alırken kaynak kodla birlikte kurulum rehberi, yapılandırma bilgileri ve temel mimari açıklamalarını da talep edin. Bu belgeler olmadan başka bir geliştiriciyle devam etmek çok zorlaşır. Bkz. yazılım kabul testi ve kaynak kod sahipliği.
Sık sorulan sorular
Kod yorumları dokümantasyon yerine geçer mi?
Kısmen. Yorumlar yerel ayrıntıları açıklar; sistemin bütününü ve kararların gerekçesini anlatmaz.
Yapay zekâ dokümantasyon yazabilir mi?
Taslak oluşturmak ve koddan özet çıkarmak için faydalıdır; ancak kararların gerekçesini yalnızca kararı verenler bilebilir.
Sonuç
İyi dokümantasyon uzun değil, işe yarar olandır. README, kurulum rehberi ve ADR'lerden oluşan küçük bir set, projenin kişilere değil ekibe ait olmasını sağlar.
