İyi Bir Tasarım Dokümanı Nasıl Yazılır

• Tasarım dokümanı, bir sistemin uygulama stratejisini, kısıtlarını ve trade-off'larını düzenleyen teknik bir rapordur
• Tasarım dokümanı, söz konusu tasarımın bağlama uygun olduğunu okuyucuya kabul ettirme ve onu ikna etme işlevi görür
• Dokümanın yapısı önemlidir; mantıklı bir akış sayesinde okuyucunun içeriği takip ederken afallamaması gerekir
• Düzenleme ile gereksiz kelimeleri azaltmak ve okuyucunun dikkat kaynaklarını korumak gerekir
• Kısa paragraflar ve ekler kullanmak, ayrıca pratik yaparak doküman yazma becerisini geliştirmek önemlidir

---

Tanım

• Tasarım dokümanı, sistem uygulama stratejisini trade-off'lar ve kısıtlar bağlamında düzenleyen bir teknik rapordur

Amaç

• Tasarım dokümanının amacı, matematikte bir ispatın bir teoremi ikna edici kılması gibi, ilgili tasarımın en iyi seçenek olduğunu okuyucuya göstermek ve onu ikna etmektir
• Tasarım sürecinde yazma eyleminin kendisi, düşüncenin titizliğini artırır
• Tasarım dokümanı yazarken belirsiz fikirler, somut düşüncelere dönüştürülebilir

Organizasyon

• İyi bir tasarım dokümanının yapısı, kod organizasyonu kadar önemlidir
• Nasıl acemiler kod yazıyorsa, birçok kişi de 'spagetti tasarım dokümanı' yazma eğilimindedir
• Cümleler mantıksal bir sıra olmadan dizildiğinde, okuyucunun bağlamı takip etmesi zorlaşır ve kafa karışıklığı oluşur
• Kusursuz bir dokümanda akış, okuyucuyu şaşırtmayacak kadar doğal olmalı; her cümle önceki içeriğin doğal bir devamı gibi gelmelidir
• Hedef, okuyucunun zihinsel durumunu anlayıp onu adım adım yeni bir duruma taşımaktır
• Beklenebilecek itirazlar önceden giderilmeli; okuyucu karşı argüman üretmeden önce açıklama yapılmalıdır

Düzenleme

• İçerik iyi organize edildikten sonra, gereksiz kelimeleri çıkarma (düzenleme) aşaması önem kazanır
• Okuyucunun dikkati sınırlı bir kaynaktır; gereksiz bilgiler cesurca silinmelidir
• Bir taslakta anlamsız ifadelerin yaklaşık %30'u azaltılabilir
• Başkalarının dokümanlarını düzenleyerek eleştirel bakış kazanmak, kendi yazınızı da daha verimli biçimde sadeleştirmenizi sağlar
• Kısa tweet'lerle (280 karakter sınırı) pratik yapmak da düşünceyi sadeleştirme ve sıkıştırma becerisini geliştirmeye yardımcı olur

Deneyim ve pratik

• Tekrarlı pratik kadar beceriyi geliştiren kısa bir yol yoktur
• Amazon'daki doküman merkezli kültür deneyimi, doküman yazma becerisini geliştirmede büyük fayda sağlamıştır
• Önemli toplantılarda önce 1 ila 6 sayfalık tasarım dokümanları dağıtılır, ardından herkes sessizce okuyup kenar boşluklarına not düştüğü bir yöntem kullanılır
• Geri bildirim alarak yazma becerisi somut biçimde geliştirilebilir

Somut ipuçları

Kısa paragraflar kullanın

• Tasarım dokümanı, art arda gelen öz ve kısa bullet point'lerle akış oluşturmalıdır
• Her bullet point (gözlem, fikir, sorun, iyileştirme vb.), tek bir kavrama odaklanan kısa bir paragraf olarak oluşturulmalıdır
• Her paragraf, tek bir cümleyle özetlenebilecek kadar açık olmalı; bu da okuyucunun kısa süreli bellek kaynaklarını korur

Eklerden yararlanın

• Karmaşık hesaplamalar veya simülasyon sonuçları, dokümanın ana gövdesinde değil eklerde ayrıntılı biçimde verilmelidir; ana metinde ise kısa dipnotlar şeklinde anılmalıdır
• Ekler, ana metindeki temel sonuçları anlamak için zorunlu olmamalı; merak eden okuyucunun başvurabilmesi için sunulmalıdır

Düzenleme örneği

• (Düzenleme öncesi, uzun paragraf):

  Her bullet point dokümanda ayrı bir paragraf olmalıdır. Her paragraf tek bir cümleyle özetlenebilmelidir. Gerçekte tek bir cümle olmak zorunda değildir; kavramı açıklamak için ek açıklamalar yer alabilir. Ancak okuyucu metni bitirdiğinde onu tek bir cümleyle özetleyebilmelidir.

• (Düzenleme sonrası, sadeleştirilmiş paragraf):

  Her bullet point bir paragraf olmalı ve tek bir cümleyle özetlenebilmelidir. Gerçekte tek cümle olmak zorunda değildir; gerekirse ek açıklama eklenebilir. Ama okunduktan sonra tek bir cümleye sıkıştırılabilmelidir.

Sonuç

• Tasarım dokümanları; düşüncenin titizliği, mantıksal akış, okuyucu odaklı düzenleme ve tekrar eden pratik yoluyla geliştirilebilen önemli bir süreçtir

[GN⁺]

Hacker News görüşü

• Yazıda özellikle etkileyici bulduğum iki alıntıyı paylaşıyor. İlki, X ekran görüntüsündeki "Yazma sürecinde fikirler 10 kat daha iyi hale geliyor" ifadesi. İkincisi ise girişteki "İkna etmeniz gereken en önemli kişi yazarın kendisidir" sözü. Sektörde yıllarca çalışmış olmalarına rağmen hâlâ tasarım dokümanlarının gerekliliğine karşı çıkan insanlar olmasına şaşırıyor. Leslie Lamport'un "Yazmak, doğanın bize düşüncemizin ne kadar dağınık olduğunu söyleme biçimidir" dediğini aktarıyor. Teknik yazma becerisini daha da geliştirmek isteyenlere Write Like an Amazonian(https://medium.com/@apappascs/…) yazısını öneriyor
  • "Sıfatları veriye dönüştürün" tavsiyesi teknoloji sektörüne o kadar yayılmış gibi ki, bugünlerde gördüğüm özgeçmişlerin hepsi sayılarla dolu ve ne anlama geldiklerini anlamak zorlaşıyor
• Bir tasarım gözden geçiricisi olarak, her doküman yazarının mutlaka içselleştirmesi gereken bir nokta olduğunu söylüyor. O da şu: "İyi bir doküman, okuyucunun problemi ve düşünce modelini anlamasını sağlayarak, haftalar süren düşüncenin sonunda ortaya çıkan çözüm tanıtıldığında bunun doğal biçimde kabul edilmesini mümkün kılar." En sevdiği alıntı ise "Daha fazla zamanım olsaydı daha kısa bir mektup yazardım" sözü. Tasarım dokümanlarının karmaşık içeriği basitleştirmesi gerektiğini, geliştiricinin yaşadığı tüm dolambaçları ve başarısızlıkları olduğu gibi dökmek için uygun yer olmadığını düşünüyor. Böyle içerikler elbette değerli olabilir ama ayrı bir dokümanda ya da eklerde düzenlenmesinin daha iyi olacağını belirtiyor. İleriye dönük yolu basit biçimde göstermek gerekiyor
  • "Daha çok zaman, daha kısa mektup" ifadesini daha çok seviyorum
  • Kendime hep şu soruları soruyorum: "Bu konuda gereksiz bir tartışma çıkar mı?", "Bu tartışmaya girmeye değer mi?" Hedefim, yeni bir okuyucunun zorlanmadan tartışmaya katılabilmesini sağlamak ve önemsiz konularda tartışma çıkmamasını sağlamak
• Amazon toplantıları, sunumu yapan kişinin nesir biçiminde bir doküman dağıtmasıyla başlıyor. Herkes sessizce oturup dokümanı okuyor ve kenar boşluklarına kırmızı kalemle notlar ve sorular yazıyor. Amazon'da fiilen çalışmış olmasa da bu yöntemin şaşırtıcı derecede etkili olduğunu ve bunu yaşamış olanların genelde çok beğendiğini söylüyor. Değerli toplantı zamanının topluca sadece okumaya gitmesi verimsiz görünebilir ama aslında insanlar önceden okuyup hazırlansa toplantılar daha kısa olabilirdi. Gerçek zamanlı eşzamanlı okuma ise yavaş okuyucuları bekletiyor ya da bağlam eksikliği nedeniyle anlama seviyeleri farklı olduğu için herkesin belirsiz biçimde vakit geçirmesine yol açıyor. Google'da tasarım değerlendirmeleri yaparken katılımcıların çoğunun hazırlıksız gelip dokümanı ilk kez orada okuyarak tartışmaya katıldığını sıkça gördüğünü anlatıyor. Bunun, Google'da güçlü bir doküman kültürü olmamasından ve ekip liderleri ya da yöneticilerin de hazırlıksız gelmesini örtük biçimde kabul etmesinden kaynaklandığını düşünüyor. İnsanların toplantıdan önce gerçekten okuyup gelmesini sağlayan bir kültür yerleşse, toplantı süresinin çok daha verimli kullanılabileceğini söylüyor
  • İnsanlar toplantıdan önce okumanın toplantı süresini azaltacağını söyler, ama Amazon'un pratiği insanların gerçekte önceden okumadığı gerçeğine verilmiş bir yanıttır. Eski ilgili bir yazıda, önceden okuyup hazırlanmaya dayalı güçlü bir kültür oluşturmanın fiilen imkânsız olduğundan söz ediliyordu. Tüm katılımcılar bir önceki toplantı yüzünden hazırlanamıyordu, o toplantının da öncesinde başka bir toplantı vardı. Teorik olarak toplantı sayısını azaltmak gerekmez mi diye eleştirilebilir, ama pratikte toplantılar değer üretiyordu ve okuma süresi dahil olsa bile kararlar alınabiliyordu. Sonuçta çıktıya odaklanmak gerekiyor ve Amazon'da bu yöntemin artılarının eksilerinden fazla olduğu düşünülüyor gibi görünüyor
  • Dokümanın ne zaman okunduğunun neden önemli olduğunu merak ediyorum. Daha fazla zamana ihtiyaç varsa toplantı süresi uzatılabilir. Dezavantajı sadece toplantıyı planlamanın zorlaşmasıysa, toplam harcanan zaman değişmiyor demektir
  • Herkes aynı anlayış seviyesinde olmadığında ya da birinin corner case'ini kaçırmaktan endişe edildiğinde daha fazla zamanın boşa gittiğini düşünüyorum
  • Gerçekte toplantıda ele alınmazsa hiçbir şeyin ilerlemediği deneyiminden söz ediyor
• Netlik ve editörlük konusunda çok iyi tavsiyeler var. Zayıf noktanın, doküman onaylandıktan sonra onun nasıl yönetileceği olduğunu söylüyor. Yönetim olmazsa bunun 'tasarım arkeolojisi' durumuna gerileyeceğini belirtiyor. Birkaç yıl önce Andrew Harmel-Law'ın, organizasyon içinde mimari kararları etkili biçimde kaydetme yöntemi olarak Architecture Decision Records(ADR'ler) önerdiğini ve bunun yardımcı olabileceğini söylüyor. ADR'ler kodun yanında bulunur (ör. adr/001-use-postgres.md) ve bağlamı, kararı ve durumu kısa biçimde kaydeder. Bu sayede her PR'da kolayca gözden geçirilebilir ve koşullar değiştiğinde kolayca yenisiyle değiştirilebilir. İlk kararın gerekçesini de aylar sonra bile arayıp bulmak mümkün olur. [Bağlantı: https://martinfowler.com/articles/…]
  • Bu yaklaşımda Security, Privacy, Compliance gibi kurum çapındaki komitelerin, ADR içeren her PR'da gözden geçirici olup olmayacağını merak ediyorum. Böyle PR'ların 90 gün içinde merge edilip edilemeyeceğinden emin değilim
  • MF.com(https://thoughtworks.com/radar/techniques/…) bağlantısını baştan sona okumam gerekecek ama "Advice Process" bölümü sonunda dönüp dolaşıp 'herkesle konuşun' demiş oluyor. Ünvanında 'Managing' geçen biri bu noktada ilgisini kaybedebilir gibi geliyor. Asıl kritik olan "dört destek unsuru", fakat ADR'leri daha fazla öğrenmek için bu bağlantıya girdim ve sonunda PDF'yi(https://thoughtworks.com/content/dam/…) indirdim. ADR'lerin gerçekte ne olduğuna dair daha net bir tanım verilse iyi olurdu
  • Session messenger tipik bir örnek. Sayısız tasarım ve mimari değişiklik yaşandığı için nasıl çalıştığını resmî olarak açıklayan otoritatif bir kaynak yok. Bu arada güvenli mesajlaşmaya ihtiyacınız varsa doğrudan Signal kullanın
• Deneyimime göre düzen ve netlik, yazılım mühendislerinin doküman yazma becerisini geliştirmesinin önündeki en büyük engeller. Yazarın 'spagetti kod' benzetmesinin, fikirleri düzenlemenin önemini anlatmak için çok iyi bir örnek olduğunu düşünüyorum. Ben de benzer bir şeyi farklı şekilde anlatmaya çalışmıştım; bundan sonra bu benzetmeyi kullanmayı planlıyorum. Daha önce benzer bir blog yazısı yazmıştım (https://ryanmadden.net/things-i-learned-at-google-design-docs/); bilgi yoğunluğu ve pratik yapmanın önemi gibi ortak noktalar ile şirkete göre değişen yönler ilginçti. 'Kısa paragraf' iddiasına ise biraz farklı bakıyorum. Kısa paragraf, bilgi iyi işlenmişse ortaya çıkar; sadece satır sonu vermek yardımcı olmaz. 'Editing' bölümünün alttaki fikri daha iyi açıkladığını düşünüyorum
• Kullandığım bir süreç var. 1. adım: Aklıma gelen her şeyi gelişigüzel dokümana döküyorum (hatta sesle yazdırmayı denemek de iyi olabilir). 2. adım: LLM'ye yapıyı ve akışı kurdurmayı deniyorum. Aslında bu aşamada çıkan sonucu çöpe de atabilirim; süreç düşünceyi sürekli rafine etmekten ibaret. 3. adım: LLM sonucunu referans alarak ya da tamamen yeni bir taslak çıkararak ilk taslağı yazıyorum. 4. adım: Kelimeleri azaltıyor, daha basit sözcüklerle değiştiriyor ve mümkün olduğunca öz hale getiriyorum. 5. adım: 4. adımı tekrarlıyorum. LLM, dağınık bir taslağı yapılandıran bir köprü işlevi görüyor. LLM'nin ürettiğini atmaya da hazır olmak gerekiyor. En az %30 her zaman kısaltılabiliyor. Kısaltırken anlam kaybolmadığını her gördüğümde şaşırıyorum
  • Kendi yazımı yeniden düzenleme sürecinin, ilk yazma kadar önemli olduğunu hissediyorum. Bu sırada sonuca ne kadar erken atladığımı ve neleri gözden kaçırdığımı fark ediyorum. Pek çok insan yazmayı, düşünceyi odaklama aracı olarak yeterince değerli görmüyor gibi. Kod için de aynı şey geçerli. Sadece şablon doldurur gibi yazıyor olsam bile, test kodu yazarken ana kodu iyileştirecek fikirler aklıma sık sık geliyor. Ama LLM böyle niteliksel iyileştirme fırsatlarını göstermiyor
  • Genişletme, kısaltma, sıkıştırma, yeniden genişletme, yeniden sıkıştırma şeklinde ilerliyor. Biri somut bir soru sorduğunda yeniden genişletiyorum, en sonunda da eğlence olsun diye düşük riskli bir özet için LLM kullanıyorum. Gerçekten de bitmeyen bir roller coaster'dayız
• Daha fazla yazmam gerektiğini düşünüyorum. Benim aklımdaki başlıca doküman yapılandırma yöntemleri B.O.O. ve Good Strategy/Bad Strategy. B.O.O., Background, Objective, Overview kısaltması; yani buraya hangi akışla gelindiğini ve neyin nasıl değiştirilmeye çalışıldığını düzenleme biçimi. Good Strategy/Bad Strategy ise tanı, yönergeler/önkabuller/gereksinimler ve aksiyonlardan oluşan bir kitap; doküman organizasyonu açısından B.O.O.'ya benziyor. B.O.O. Google veya küçük ekipli organizasyonlarda iyi çalışıyor, Good Strategy/Bad Strategy ise çok daha farklı ölçeklere uygulanabiliyor ama güçlü kalem gerektiriyor
• Teknik yazı dersi alırken, ana noktaları net biçimde özetleme becerimin büyük ölçüde geliştiğini fark ettim. 'Kırmızı kalemle kesme' yöntemine odaklandım (yaz, üstünü çiz, yeniden yaz); amaç kavramı olabilecek en az kelimeyle aktarmaktı. Bu süreç birkaç aşamaya ayrılıyor ve pratik yaptıkça kolaylaşıyor. Bu yetkinliği ekip arkadaşlarımla da paylaşmaya çalışıyorum ama bunun düzenli alıştırma gerektiren bir beceri olduğunu kendime sürekli hatırlatıyorum
• Bu tür yazılmış dokümanları ve genel olarak bu yazma kültürünü gerçekten seviyorum. Ama bu yaklaşımın ters etki yarattığı durumları da gördüm. Sonuca nasıl varıldığını ve bunun arkasındaki mantığı açıklamak, ikna etmeye dönük dokümanlarda çok etkili. Ancak her zaman böyle bir ikna süreci gerekmiyor. Bazen sonucu doğrudan en başta yazmak, özellikle de yazara güvenen okuyucular için daha iyi olabiliyor. Çoğu durumda okuyucu mantık zincirini adım adım takip ederken yorulmak yerine önce ana fikri bilmek istiyor. Sonucu öğrendikten sonra ayrıntılı mantığı takip etme isteği doğuyor
  • Üste kısa bir özet koyup, ayrıntılı açıklama ve gerekçeleri aşağıda sürdürmek de gayet iyi bir yapı olabilir
• Bazen yalnızca benim okuyacağım bir tasarım dokümanını kendim için yazıyorum. Bir şeyi yazılı hale getirmenin tek başına bile çok güçlü olduğunu hissediyorum. Gerçek örnek dokümanlar olsa gerçekten yardımcı olurdu; kendi doküman yapımı başkalarının son hâliyle karşılaştırmak isterdim