İyi bir README, projeyi hiç görmemiş bir geliştiricinin ilk çalışan sonuca ulaşmasına yardım eder. Zamanla bu dosya koddan kopabilir: Değişen ortam değişkenleri, kaldırılan komutlar ve eski ekran görüntüleri birikir. Codex ile belge iyileştirme işini yalnızca metni güzelleştirme olarak tanımlamak bu sorunları çözmez. Daha yararlı hedef, belgedeki her uygulanabilir adımın mevcut projeyle ilişkisini kurmaktır.
Belgenin okuyucusunu ve görevini seçin
Kurulum belgesi, mimari açıklama ve yönetici kılavuzu farklı soruları yanıtlar. Hepsini tek dosyaya doldurmak okuyucunun aradığını bulmasını zorlaştırır. Örneğimizde yeni bir ekip üyesinin yerel geliştirme ortamını hazırladığı bir README üzerinde çalışıyoruz. İlk hedef; projeyi açmak, gerekli yapılandırmayı yapmak ve örnek sayfayı görmek olsun.
Mevcut belgeyi değerlendirirken okuyucunun hangi bilgiyi zaten bildiğini varsaydığınızı yazın. Örneğin veritabanının ayrıca kurulması gerekiyorsa bunu “ön koşullar” içinde görünür kılın. Ekibin kendi bilgisayarında yıllardır hazır bulunan bir servis, yeni geliştiricinin bilgisayarında bulunmayabilir. Eksik ön koşul çoğu zaman yanlış komuttan daha fazla zaman kaybettirir.
Koddan doğrulanabilen bilgileri toplayın
Codex'ten paket yapılandırmasını, ortam örneğini ve mevcut başlatma dosyalarını karşılaştırmasını isteyin. Bir değişkenin kodda bulunması, her kurulumda zorunlu olduğu anlamına gelmez. Bu yüzden zorunlu, isteğe bağlı ve yalnızca belirli özelliklerde kullanılan ayarlar ayrılmalıdır. Gizli değerleri belgeye taşımak yerine yer tutucular ve örnek değerler kullanın.
Örnek görev şöyle yazılabilir:
README'nin yerel kurulum bölümünü mevcut kaynakla karşılaştır. Paket dosyaları ve örnek yapılandırmadan doğrulayabildiğin adımları düzelt. Doğrulayamadığın servis gereksinimlerini kesin bilgi gibi yazma. Gerçek parola veya anahtar ekleme. Yeni geliştiricinin izleyebileceği sırayı koru; komutları çalıştırdıysan sonucu, çalıştırmadıysan nedenini belirt.
Bu talimat belge üretimini kod davranışına bağlar. Belgede olmayan yeni bir ürün özelliği tasarlama isteği içermez.
Örnekleri küçük ve yeniden denenebilir tutun
Bir API örneği, yüzlerce satırlık bir istek yerine tek davranışı göstermelidir. Örneğin filtre parametresini anlatırken hem tarih aralığı hem sıralama hem yetki senaryosunu aynı örneğe yüklemeyin. Girdi, beklenen çıktı ve gerekli bağlam yan yana bulunursa örneğin yanlış olduğunu fark etmek kolaylaşır.
Hata çözümleme bölümünde de belirtiyle nedeni ayırın. “Bağlantı başarısızsa veritabanını yeniden kurun” gibi geniş öneriler yerine adres, erişim ve servis durumu gibi kontrol edilebilir noktaları açıklayın. Codex'in önerdiği çözümün gerçekten bu projede geçerli olduğuna kaynak üzerinden bakın; yaygın bir teknik doğru, özel kurulumunuz için eksik olabilir.
Belgeyi okuyucu gibi son kez uygulayın
Son kontrolde yalnızca yazım ve bağlantıları değerlendirmeyin. Adımları sırasıyla takip ederek ilk başarı noktasına ulaşılabiliyor mu? Bir adım başka bölümde açıklanan dosyaya bağlıysa bağlantısı var mı? Arayüzdeki düğme adları belgeyle aynı mı? Bu sorular belgenin kullanılabilirliğini gösterir.
Teknik ayrıntıların uzun açıklaması gerekiyorsa README'den ayrı bir belgeye bağlantı verin. Ana dosya ilk kurulumu ve sık kullanılan yolları görünür tutsun. Sonuç, daha uzun bir README değil, okuyucunun hangi adımı neden yaptığını anlayarak ilerleyebildiği güncel bir başlangıç noktası olmalıdır.
Belge değişikliklerini kod incelemesinde ayrıca okuyun. Bir komutun çıktısı başarılı olsa bile okuyucu hangi dosyayı değiştireceğini anlayamayabilir. Dosya yolları, beklenen ekran ve sonraki adımın kısa açıklaması birlikte verildiğinde belge, komut listesinin ötesine geçer ve yeni başlayan kişinin hatayı kendi başına ayırt etmesine yardım eder.
Resmî kaynak: OpenAI — Prompting, belge güncelleme iş akışı.
