Kazanimlar:
- AI ile hedef kitleye ve kaynağa dayalı README, docstring ve changelog taslakları üretebilme
- Dokümantasyonda 'ne/nasıl' ile 'neden' katmanlarını ayırıp neden'i insan olarak ekleyebilme
- Kurulum adımlarını bizzat çalıştırarak doğrulayıp dokümanı kod değişikliğinin parçası yapabilme
Yazılımın en sık ihmal edilen ama en uzun ömürlü parçası dokümantasyondur. Kod aylar sonra bile okunur; onu yazan kişi ayrılmış, bağlam unutulmuş olur ve geriye yalnızca yazılanlar kalır. İyi bir README (bir projenin ne olduğunu, nasıl kurulup çalıştırılacağını anlatan giriş belgesi), açıklayıcı kod yorumları ve güncel bir API dokümantasyonu (bir arayüzün nasıl kullanılacağını anlatan referans), bir ekibin hızını doğrudan belirler. Yapay zeka, dokümantasyonun "yazma yorgunluğunu" büyük ölçüde alır — ama bir tuzağı vardır: AI, koddan ne yaptığını çıkarabilir, ama neden öyle yapıldığını çoğu zaman bilemez.
Bu ünitede AI ile README, kod yorumu, docstring (fonksiyon/sınıf başına yazılan açıklama bloğu), API dokümanı ve değişiklik günlüğü (changelog) üretmeyi; ve dokümantasyonun en değerli kısmı olan "neden"i insan olarak nasıl koruyacağınızı ele alıyoruz.
"Ne" ile "Neden" Ayrımı
Dokümantasyonun iki katmanı vardır. Birincisi ne/nasıl: "bu fonksiyon bir listeyi sıralar", "kurulum için şu komutu çalıştırın". Bunlar koddan ve yapıdan çıkarılabilir; AI burada çok başarılıdır. İkincisi neden: "bu servisi neden senkron değil asenkron yaptık", "bu sınır değeri neden 30 saniye", "bu kütüphaneyi neden diğerine tercih ettik". Bunlar kodda yazmaz; tasarım kararlarının, kısıtların ve geçmiş acıların ürünüdür.
AI "neden"i bilmez; en fazla makul bir tahmin uydurur — ki bu tehlikelidir, çünkü yanlış bir gerekçe hiç gerekçe olmamasından daha kötüdür. Bu yüzden iş bölümü nettir: AI "ne/nasıl"ı taslaklar, siz "neden"i eklersiniz. En değerli yorum, kodun söyleyemediğini söyleyen yorumdur.
İpucu: Kodun kendisinin açıkça anlattığı şeyi yorumla tekrarlamayın (i = i + 1 // i'yi bir artır gibi). AI bazen bu tür gereksiz yorumlar üretir; onları eleyip enerjinizi "neden" yorumlarına ayırın.
Adım Adım: AI ile Dokümantasyon Üretimi
- Hedef kitleyi belirtin. "Yeni başlayan bir geliştirici", "bu API'yi kullanacak dış ekip", "gelecekteki ben" — kitle, dilin ve derinliğin tonunu belirler.
- Kaynağı verin. İlgili kodu, mevcut README'yi, örnek kullanımı prompt'a ekleyin. Kaynaksız doküman, uydurmaya davetiyedir.
- Yapı dayatın. README için standart bölümler (Amaç, Kurulum, Kullanım, Yapılandırma, Katkı), docstring için proje formatı.
- "Neden" boşluklarını işaretletin. AI'dan, gerekçesini bilmediği kararları "burada bir 'neden' notu gerekli" diye işaretlemesini isteyin; sonra o boşlukları siz doldurun.
- Doğrulayın. Kurulum adımlarını gerçekten çalıştırın; örnek kodu deneyin. Çalışmayan bir README, hiç README olmamasından beterdir.
Üç Mini Vaka
Vaka 1 — README onboarding'i hızlandırdı. Bir açık kaynak aracın README'si eksikti; yeni katkıcılar ortalama 2 saat kurulumla boğuşuyordu. Ekip, kurulum betiklerini ve package.json'ı AI'ya verip yapılandırılmış bir README taslattı, ardından adımları temiz bir makinede bizzat çalıştırıp iki eksik bağımlılığı ekledi. Sonraki katkıcıların kurulum süresi ortalama 25 dakikaya indi.
Vaka 2 — Uydurulmuş "neden" tuzağı. Bir geliştirici, bir zaman aşımı değerinin (timeout=30) yanına AI'dan yorum istedi. AI, "yüksek ağ gecikmesini tolere etmek için" diye makul ama yanlış bir gerekçe yazdı; gerçek neden, aşağı akıştaki bir servisin sözleşmesel 30 saniyelik sınırıydı. Yanlış yorum, sonraki bir geliştiriciyi değeri gereksiz yere artırmaya yöneltip bir olaya yol açtı. Ders: gerekçeyi kod sahibi doğrulamalı.
Vaka 3 — Docstring standardı otomatikleşti. 40 fonksiyonluk bir yardımcı modülde hiç docstring yoktu. AI'ya proje formatı (Google stili) verilip her fonksiyon için parametre, dönüş ve istisna açıklamaları ürettirildi; geliştirici bunları gözden geçirip birkaç yanlış tip açıklamasını düzeltti. 40 fonksiyonun belgelenmesi yaklaşık yarım günden bir saate indi.
Dört Kopyalanabilir Şablon
Yapılandırılmış README taslağı:
Hedef kitle: {{ör. yeni katkıcı}}.Aşağıdaki dosyalardan yola çıkarak bir README taslağı yaz. Bölümler: Amaç,Özellikler, Gereksinimler, Kurulum, Çalıştırma, Yapılandırma, Test, Katkı.Kurulum/çalıştırma komutlarını gerçek dosyalardan çıkar; UYDURMA. Emin olmadığınyerleri "[DOĞRULA]" ile işaretle.Kaynak: {{package.json / betikler / örnek kod}}
Docstring / API referansı:
Bu fonksiyonlara {{proje stili: Google/NumPy/JSDoc}} formatında docstring yaz:kısa özet, parametreler (tip + anlam), dönüş, fırlatılan istisnalar, 1 kısa örnek.Kodun AÇIKÇA söylediğini tekrarlama. "Neden" gerektiren tasarım kararlarını"[NEDEN GEREKLİ]" diye işaretle, uydurma gerekçe yazma.{{kod}}
"Neden" yorumu için boşluk çıkarma:
Bu kodda, bir sonraki geliştiricinin "neden böyle?" diye soracağı noktalarılistele (sihirli sayılar, alışılmadık kararlar, geçici çözümler). Her biri içinbir yorum İSKELETİ ver ama gerekçeyi BOŞ bırak; gerekçeyi ben dolduracağım.{{kod}}
Changelog / PR açıklaması:
Aşağıdaki diff'ten bir {{changelog girdisi / PR açıklaması}} yaz.Format: Ne değişti (kullanıcı diliyle), Neden (issue: {{...}}), Kırıcı değişiklik(varsa), Test edildi mi. Teknik jargonu hedef kitleye göre ayarla.{{diff}}
Zayıf prompt / Güçlü prompt
Zayıf: "Bu projeye README yaz."
Güçlü: "Hedef kitle: bu repoyu ilk kez klonlayan bir geliştirici. Ekteki package.json, docker-compose.yml ve scripts/ klasöründen yola çıkarak Amaç, Gereksinimler, Kurulum, Çalıştırma, Test, Katkı bölümleriyle bir README taslağı yaz. Komutları bu dosyalardan çıkar, uydurma; emin olmadığın her yeri [DOĞRULA] ile işaretle."
Güçlü sürüm kitleyi, kaynağı, yapıyı ve "uydurma, işaretle" kuralını verir; böylece doküman gerçek dosyalara dayanır ve doğrulanacak yerler açıkça görünür.
Doküman türü
AI iyi yapar
İnsan ekler/doğrular
README kurulum
Adım taslağı
Adımları çalıştırıp teyit
Docstring/API
Yapı, parametre, tip
Doğru tip ve "neden"
Kod yorumu
"Ne yapıyor" özeti
"Neden böyle" gerekçesi
Changelog/PR
İlk taslak
Etki ve doğruluk
Mimari karar (ADR)
İskelet
Gerçek kararlar ve tavizler
Dokümantasyon Bakım İster
Bir dokümanın en tehlikeli hâli, yanlış olduğu hâlde doğru görünmesidir. Kod değişip doküman güncellenmediğinde, okuyanı aktif olarak yanıltır. AI, güncellemeyi kolaylaştırır: bir diff verip "bu değişiklik hangi doküman bölümlerini etkiler?" diye sorabilirsiniz. Ama güncelliği güvence altına alan şey süreçtir — dokümantasyon güncellemesini kod değişikliğinin bir parçası (PR'ın kabul kriteri) yapın. AI hızlandırır; disiplini ekip kurar.
Dikkat: Bir README'deki kurulum adımlarını doğrulamadan yayımlamayın. "Muhtemelen çalışır" bir belge, yeni gelen bir geliştiricinin ilk gününü mahvedebilir ve güveni sarsar. Adımları temiz bir ortamda bizzat çalıştırın.
Sık yapılan hatalar
- "Neden"i AI'ya uydurtmak. Yanlış gerekçe, gerekçesizlikten kötüdür; tasarım nedenini kod sahibi yazmalı.
- Kurulum adımlarını doğrulamamak. Çalışmayan README güveni yıkar.
- Kodu tekrarlayan gereksiz yorum. Gürültü üretir, gerçek "neden" yorumlarını gölgeler.
- Hedef kitle belirtmemek. Kime yazıldığı belirsiz doküman ne acemiye ne uzmana yarar.
- Güncellemeyi süreçten ayırmak. Doküman kodla birlikte güncellenmezse hızla yanıltıcı hâle gelir.
Özetle
AI, dokümantasyonun mekanik yükünü büyük ölçüde alır: README, docstring, API referansı, changelog ve PR açıklamalarını hızlı taslaklar. Ama en değerli katman olan "neden"i bilemez ve uydurması tehlikelidir. İş bölümü nettir: AI "ne/nasıl"ı üretir, siz "neden"i eklersiniz. Kitleyi belirtin, kaynak verin, yapı dayatın, uydurulacak yerleri işaretletin ve her kurulum adımını bizzat çalıştırarak doğrulayın. Dokümantasyonu, kod değişikliğinin ayrılmaz bir parçası hâline getirin.
Uygulama görevi
Dokümantasyonu eksik veya eski olan bir modül ya da küçük bir proje seçin. Önce "yapılandırılmış README taslağı" (veya docstring) şablonuyla AI'dan bir taslak üretin; kaynağı ve hedef kitleyi mutlaka verin. Sonra AI'nın [DOĞRULA] veya [NEDEN GEREKLİ] diye işaretlediği her noktayı gezin: kurulum adımlarını gerçekten çalıştırın ve tasarım "neden"lerini kendi bilginizle doldurun. Kaç adımın düzeltilmesi gerektiğini ve kaç "neden" eklediğinizi not edin.
Kontrol listesi
- [ ] Dokümantasyonda "ne/nasıl" ile "neden" katmanlarını ayırt ediyorum.
- [ ] "Neden"i AI'ya uydurtmuyor, kendim ekliyorum.
- [ ] Prompt'a hedef kitleyi ve gerçek kaynak dosyaları veriyorum.
- [ ] AI'nın işaretlediği [DOĞRULA] noktalarını bizzat çalıştırarak teyit ediyorum.
- [ ] Kodu tekrarlayan gereksiz yorumları eliyorum.
- [ ] Dokümantasyon güncellemesini kod değişikliğinin bir parçası hâline getiriyorum.