- Design docs, Google’ın yazılım mühendisliği kültürünün temel unsurlarından biridir; bir yazılım sistemi ya da uygulamasının ana yazarı tarafından, kodlama projesine başlamadan önce yazılan görece gayriresmî belgelerdir
- Yüksek seviyeli uygulama stratejisini ve temel tasarım kararlarını dokümante eder; özellikle de bu kararlar alınırken değerlendirilen trade-off’lara odaklanır
- Yazılım mühendisinin işi kod yazmak değil, problem çözmektir; Design doc gibi yapılandırılmamış metinler, projenin erken aşamalarında koda kıyasla daha özlü ve anlaşılması kolay bir problem çözme aracı olabilir
Design docs’un yazılım geliştirme yaşam döngüsündeki rolü
- Asıl yazılım tasarımı dokümantasyonunun yanı sıra şu işlevleri de yerine getirir:
- Değişiklikler hâlâ düşük maliyetliyken tasarım sorunlarını erken tespit etmek
- Kurum içinde tasarım konusunda uzlaşı sağlamak
- Yatay kesen konuların (cross-cutting concerns) dikkate alınmasını güvence altına almak
- Kıdemli mühendislerin bilgisini organizasyona yaymak
- Tasarım kararları için kurumsal hafızanın temelini oluşturmak
- Yazılım tasarımcılarının teknik portföyünde özet bir artefakt işlevi görmek
Design doc’un yapısı
- Design doc, katı içerik yönergeleri olmayan gayriresmî bir belge olduğundan, belirli projeye en uygun formatta yazılması esastır
- Context and scope: Yeni sistemin hangi bağlamda kurulduğuna ve fiilen neyin inşa edileceğine dair genel bir bakış sunar
- Goals and non-goals: Sistemin hedeflerini ve hedef dışı olanları listeler
- The actual design
- System-context-diagram: Sistemi daha büyük teknik ortamın bir parçası olarak gösteren diyagram
- APIs: Sistemin sunduğu API’lerin taslağı
- Data storage: Verinin nasıl saklanıp yönetileceğine dair tartışma
- Code and pseudo-code: Yalnızca yeni algoritmalar açıklanırken eklenir
- Degree of constraint: Çözüm alanındaki kısıt düzeyi, tasarım belgesinin biçimini etkileyen başlıca etkenlerden biridir
- Alternatives considered: Benzer sonuca makul şekilde ulaşabilecek alternatif tasarımları listeler; her birinin trade-off’larını ve neden ana tasarımın seçildiğini açıklar
- Cross-cutting concerns: Güvenlik, gizlilik, gözlemlenebilirlik gibi ortak kurumsal ilgi alanlarının tasarımı nasıl etkilediğini açıklar
Design doc ne zaman yazılmalı
- Design doc yazılıp yazılmayacağı, kurumsal uzlaşı, dokümantasyon ve kıdemli incelemesi gibi faydaların, belge yazmanın getirdiği ek işten daha büyük olup olmadığına bağlıdır
- Problemin ya da çözümün karmaşıklığı nedeniyle tasarım sorununa getirilecek çözüm belirsiz değilse, belge yazmanın değeri düşüktür
- Uygulama kılavuzuna yakın bir Design doc gereksiz olabilir
- Prototipleme ve hızlı iterasyon için Design doc yazma yükü uygun olmayabilir
Design doc’un yaşam döngüsü
- Creation and rapid iteration: Belgenin yazılması ve ekip arkadaşlarıyla hızlı iterasyon sayesinde kararlı bir sürüme ulaşılması
- Review: Daha geniş bir kitleyle paylaşılıp incelenmesi
- Implementation and iteration: Uygulama sırasında tasarım değişiklikleri olduğunda belgenin güncellenmesi
- Maintenance and learning: Sistemi anlamak için en erişilebilir giriş noktası olarak hizmet etmesi
GN⁺ görüşü
- Design doc, karmaşık yazılım projelerinin en zor problemlerini çözerken netlik kazanmak ve uzlaşı sağlamak için iyi bir yöntemdir. Ön araştırma sayesinde gereksiz kod yazımını önleyerek maliyeti düşürebilir; ancak yazım ve inceleme için zaman gerektirdiğinden bir maliyet de yaratır
- Bu nedenle, projeye uygun şekilde Design doc yazılıp yazılmayacağına akıllıca karar verilmelidir. Yazılım tasarımında belirsizlik varsa, kıdemli mühendislerin erken müdahalesi faydalı olacaksa, tasarım konusunda kurumsal uzlaşı gerekiyorsa, ekip güvenlik gibi ortak konuları sık sık gözden kaçırıyorsa ya da legacy sistem tasarımı için high-level bir belgeye ihtiyaç varsa Design doc düşünülmeye değerdir
- Bu, yazılım tasarım sürecinde dokümantasyonun önemini iyi gösteren bir örnek; özellikle büyük ekiplerde tutarlı bir tasarım kültürü oluşturulmasına yardımcı olabilir. Ancak mühendisler dokümantasyon yükü nedeniyle bundan kaçınabileceği için, duruma uygun seviye ve kapsamda yönergeler belirlemek önemlidir
- Kişisel olarak, 1) tasarımın karmaşıklığına göre trade-off’ları değerlendirme, 2) uygulama öncesinde tasarım sorunlarını erken keşfetme, 3) yeni üyelerin hızlı öğrenmesi için sistem özeti sunma açısından Design doc’un çok faydalı olduğunu düşünüyorum. Ancak aşırı biçimsel ya da gerçek uygulamadan kopuk bir belgeye dönüşmemesine dikkat etmek gerekir
- Projenin başlangıcında ya da karmaşıklığın yüksek olduğu tasarım aşamalarında Design doc’u zorunlu kılmak, ancak mühendislerin bunu gönüllü olarak yazmasını teşvik edecek teşvikler sunmak da bir yöntem olabilir. Belge yazımının bireysel mühendislerin teknik portföyünü güçlendirmeye de yardımcı olduğu vurgulanabilir
1 yorum
Hacker News görüşü
Google'ın tasarım dokümanı kültürü hakkında çeşitli görüşler: