Ekibin gerçekten okuyacağı bir teknik tasarım belgesini nasıl yazarım?
Soru
Yeni bir özelliğe ya da mimari değişikliğe başlamadan önce RFC/tasarım belgesi yazıyorum. Ama belgelerim genelde birkaç thumbs-up emojisi alıyor ve sonra herkes kafasına göre farklı bir şey inşa ediyor. Yani belge okunmuyor ya da okunuyorsa bile ortak bir karara dönüşmüyor. Ekibin gerçekten okuyacağı ve üzerinde hizalanacağı bir teknik tasarım belgesini nasıl yazarım? Formattan çok davranışsal, yaşanmış tavsiye arıyorum.
Cevap
Kısa cevap
Herkesin farklı bir şey inşa etmesinin sebebi belgenin uzunluğu değil; belirsizlik ve ortada açık bir kararın olmaması.
Bağlam
Thumbs-up bir onay değildir. İşe yarayan belge, okuyanı hizalanmaya zorlayan belgedir.
Ne yapmalı
-
Problemi ve bağlamı en başa koyun, çözümü değil. İnsanlar tarar. İlk paragrafta “neyi, neden şimdi, hangi kısıtlarla çözüyoruz” olsun. En üste 3-4 cümlelik bir özet (TL;DR) koyun; kimse çözüm detayına inmeden önce derdi anlasın.
-
Non-goal’ları yüksek sesle yazın. Herkesin farklı şey inşa etmesinin bir numaralı sebebi budur: kapsam belirsiz kalır, herkes boşluğu kendi varsayımıyla doldurur. “Bu belge şunu kapsamıyor” listesi, çözümün kendisinden daha fazla çatışma önler.
-
Reddettiğiniz alternatifleri ve nedenini yazın. Asıl hizalanma burada olur. “A’yı değil B’yi seçtim çünkü…” demezseniz, okuyan kişi kafasındaki A’yla ayrılır ve onu inşa eder. Reddedilen seçenekler belgenin en değerli kısmıdır.
-
Kısa tutun — uzunluk bir maliyettir. Kimsenin bitirmediği belge kimseyi hizalamaz. Acımasızca kesin. On sayfalık bir tasarım genelde iki sayfalık bir karar artı kaçınılan bir tartışmadır.
-
Açık bir karar zorlayın; sessizlik onay değildir. Belirli kişileri belirli bölümlere etiketleyin, somut sorular sorun (“bu şemayı onaylıyor musun?”), bir review deadline’ı koyun. Gerekirse 30 dakikalık bir karar toplantısıyla kapatın. Emoji değil, açık bir “onaylandı/itirazım şu” hedefleyin.
-
Belge bir anıt değil, canlı bir kayıttır. Tartışmayı belgeye geri işleyin, kararları satır içinde not düşün, bir değişiklik günlüğü tutun. Onaydan sonra da tek doğru kaynak o olmalı: ticket’lardan ona link verin, gerçek uygulama saptığında belgeyi güncelleyin, yoksa iki hafta içinde ölür.
Sonuç: Ben olsam belgeyi “okunacak bir doküman” gibi değil, “bir karara varmak için düzenlenmiş bir tartışma” gibi kurgularım. Tarayan biri için yazarım: problem ve non-goal’lar en üstte, reddedilen alternatifler görünür, karar açıkça sorulmuş. En önemlisi, thumbs-up’ı asla hizalanma sanmam — herkesin farklı şey inşa etmesi, kimsenin aslında bir şeye taahhüt etmediğinin kanıtıdır. Zorlayıcı bir fonksiyon (deadline, atanmış onaylayıcı, kısa karar toplantısı) koymadan bu döngü kırılmaz.
Sahada karşılaşılan ve bana sorulan sorulardan derlendi.
İlgili Yazılar
Yorumlar
Yorum yapmak için GitHub hesabınızla giriş yapmanız yeterli. Yorumlar GitHub Discussions üzerinde saklanır.