Teknik tasarım belgesi, TDD veya tech design document olarak da adlandırılır; bir yazılım özelliğinin veya sisteminin nasıl inşa edileceğini açıklayan yazılı bir plandır. Uygulama başlamadan önce oluşturulur ve proje boyunca mühendisler, incelemeciler ve paydaşlar için tek gerçek kaynak görevi görür. Bu rehber, bir teknik tasarım belgesinin neleri içerdiğini, çoğu ekibin izlediği standart biçimi ve bir tanesini verimli bir şekilde nasıl yazacağınızı ele alır.
Teknik tasarım belgesi nedir
Yazılım mühendisliği bağlamında teknik tasarım dokümantasyonu, bir yazılım projesi veya özelliği için teknik yaklaşımı, mimariyi ve uygulama planını açıklayan yazılı bir çıktıdır. Neyin inşa edileceğini, nasıl inşa edileceğini ve hangi kararların neden alındığını kapsar. Amacı, kod yazılmadan önce ortak bir anlayış oluşturmak, maliyetli yanlış anlamaları azaltmak ve geliştirme aşamasını herkes için daha sorunsuz hale getirmektir.
TDD, sistemin kullanıcı açısından ne yapması gerektiğini açıklayan ürün gereksinimleri belgesinden (PRD) farklıdır. Teknik tasarım belgesi, mühendislik ekibinin bu gereksinimleri teknik olarak nasıl uygulayacağını açıklar. Bu iki belge birlikte çalışır: PRD problemi tanımlar, TDD ise çözümü tanımlar.
Teknik tasarım belgeleri genellikle özelliğin baş mühendisi veya mimarı tarafından yazılır, daha geniş mühendislik ekibi ve ilgili paydaşlar tarafından incelenir ve geliştirme başlamadan önce onaylanır.
Standart teknik tasarım belgesi biçimi
Biçimler ekipler arasında farklılık gösterse de, aşağıdaki bölümler çoğu mühendislik organizasyonunda ve teknik tasarım belgesi şablonunda kullanılan yapıyı temsil eder.
Belge başlığı: Belgeyi tanımlanabilir ve izlenebilir kılan meta veriler: - Özellik veya proje adı - Yazar - Oluşturulma ve son güncellenme tarihi - Sürüm numarası - İncelemeciler ve onay durumu
Genel bakış: Belgenin neyi kapsadığına, neyin inşa edildiğine ve bunun neden önemli olduğuna dair kısa bir özet. Bu bölüm iki dakikadan kısa sürede okunabilir olmalı ve herhangi bir incelemeciye belgenin geri kalanını anlaması için yeterli bağlamı sunmalıdır.
Hedefler ve amaçlar: Bu tasarımın çözdüğü belirli sorunlar ve ulaşmayı amaçladığı sonuçlar. Ölçülebilir başarı kriterleri varsa burada yer almalıdır.
Kapsam: Bir TDD, bu tasarıma nelerin dahil olacağını ve bu aşamada açıkça kapsam dışında bırakılanları netleştirmelidir. Kapsam dışı öğeleri belirtmek, kapsam kaymasını önler ve inceleme tartışması için net sınırlar belirler.
Arka plan ve bağlam: Mevcut sistemin neden şu anki şekilde çalıştığı, daha önce nelerin denendiği ve yeni tasarımın hangi kısıtlamalar veya kararlar çerçevesinde çalışması gerektiği. Bu bölüm, önceki kararlara katılmamış incelemecilerin gerekçeleri anlamasına yardımcı olur.
Sistem tasarımı ve mimarisi: Temel teknik bölüm. Şunları içerir: - Bileşenlerin nasıl bir araya geldiğini ve aralarında verinin nasıl aktığını gösteren mimari diyagramlar - Teknik yaklaşımın üst düzey açıklaması - Temel teknoloji seçimleri ve bunların ardındaki gerekçe
Ayrıntılı bileşen tasarımı: Uygulamada yer alan her bileşenin, servisin veya modülün ayrıntılı dökümü. Bu, sınıf yapılarını, arayüz imzalarını, veri türlerini, girdi/çıktı spesifikasyonlarını ve bir bileşenin kullandığı belirli algoritmaları içerebilir.
Veri modeli: Veritabanı şeması değişiklikleri, varlık ilişkileri ve öznitelik türleri dahil olmak üzere ilgili veri yapıları. Yeni tablolar, koleksiyonlar veya alanlar burada tanımlanmalıdır.
API tasarımı: Uç nokta tanımları, istek ve yanıt biçimleri, kimlik doğrulama gereksinimleri ve hata yönetimi. Bu bölüm, API'ler sunan veya tüketen sistemler için kritik öneme sahiptir.
Güvenlik değerlendirmeleri: Tasarımın kimlik doğrulamayı, yetkilendirmeyi, veri şifrelemesini ve bu özellikle ilgili bilinen saldırı vektörlerini nasıl ele aldığı. Güvenliği burada ele almak, sonradan eklemekten daha ucuzdur.
Test stratejisi: Uygulamanın nasıl doğrulanacağı: birim testleri, entegrasyon testleri, uçtan uca testler ve gerekli olabilecek herhangi bir manuel test. Özelliğe ilişkin kabul kriterleri burada yer alabilir.
Bağımlılıklar ve riskler: Bu tasarımın bağlı olduğu harici sistemler, servisler veya ekipler. Bilinen riskler, açık sorular ve çözülmemiş kararlar, incelemecilerin nereye odaklanması gerektiğini bilmesi için burada listelenmelidir.
Revizyon geçmişi: Belgede yapılan önemli değişikliklerin tarih ve yazarlarıyla birlikte kaydı.
Kimi Docs ile teknik tasarım dokümantasyonu taslağı oluşturun ve geliştirin
Teknik tasarım dokümanını sıfırdan yazmak çoğu zaman tekrarlayan, sıkıcı bir kalıp işi gibi hissettirir. Yapıyı biçimlendirmek için saatler harcamak yerine, sürecin temelini oluşturmak için Kimi Docs'u akıllı bir AI doküman ajanı olarak kullanabilirsiniz.
Ürün gereksinimlerinizi, önceki mimari desenlerinizi veya API referanslarınızı yükleyip geliştirdiğiniz özelliği tanımlamanız yeterli. Kimi, tüm standart mühendislik bölümleri zaten yerinde olacak şekilde, yüksek düzeyde yapılandırılmış bir teknik doküman üretir. Bu sayede düzen kurma aşamasını atlayıp enerjinizi belirli tasarım kararlarına, mimari ödünleşimlere ve uygulama detaylarına optimize etmeye odaklayabilirsiniz.
Adım 1: Mevcut bağlamı yükleyin ve özelliği tanımlayın
İlgili dokümanları (ürün gereksinimleri, önceki tasarım dokümanları, API referansları) yükleyin ve Kimi'ye özelliğin ne olduğunu ve genel hatlarıyla nasıl çalışacağını anlatın.
Adım 2: Kimi'den TDD yapısını oluşturmasını isteyin
İhtiyaç duyduğunuz bölümleri ve gereken detay seviyesini tanımlayın.
Adım 3: Gözden geçirin, iyileştirin ve detayları tamamlayın
Kimi, ekibe özgü detaylar gerektiren bölümler için yer tutucu içeriklerle yapılandırılmış bir taslak oluşturur. Her bölümü inceleyin ve genişletmek, netleştirmek veya düzenlemek için takip promptları gönderin.
Adım 4: Tamamlanan dokümanı indirin
TDD'yi bir Word dosyası veya PDF olarak dışa aktarın; incelemecilerle paylaşmaya veya dokümantasyon sisteminize eklemeye hazır hale getirin.
Kimi Docs'un temel özellikleri
Bir özellik tanımından tam TDD yapısını oluşturma: Boş bir belgeyle başlamak yerine Kimi, sağladığınız bağlama dayanarak tüm standart bölümleri doldurulmuş şekilde yapılandırılmış bir taslak üretir; bu bölümler, ilk taslakta genellikle atlanan güvenlik değerlendirmeleri, test stratejisi ve revizyon geçmişi gibi kısımları da içerir. İskelet otomatik olarak oluşturulur; ekibe yalnızca kendisinin sağlayabileceği belirli kararlar, ödünleşimler ve mimari detaylara odaklanmak kalır.
Uzman incelemesi ve açıklama ekleme: Ekibinizin zaten mevcut bir TDD'si varsa Kimi Docs, bunu bir teknik akran gibi inceleyerek kapsam eksikliklerini, bölümler arasındaki tutarsızlıkları veya gerekçenin açıkça belgelenmediği alanları işaretleyebilir. Bu, resmi bir tasarım incelemesinden önce veya mevcut bir sisteme yeni bir mühendisi dahil ederken faydalıdır.
Teknoloji yığınınıza ve içerik biçimlerinize uyum sağlama: Dil, veritabanı, framework'ler veya API'ler gibi ilgili spesifik teknolojileri belirtin; Kimi, teknik bölümleri buna göre uyarlar. Kod blokları, veri şemaları, API spesifikasyonları ve matematiksel gösterimler yerel olarak işlenir; böylece içerik ne kadar teknik olursa olsun çıktı okunabilir ve düzgün yapılandırılmış kalır.
Aynı anda birden fazla dokümanı işleme: Mevcut bir TDD'yi güncellemeniz veya önceki bir tasarıma dayanarak yeni bir tane oluşturmanız gerekiyorsa, her ikisi de aynı promptta yüklenip referans olarak kullanılabilir.
Teknik tasarım dokümanı yazma ipuçları
Etkili bir teknik tasarım dokümanı, uygulama ve inceleme için kalıcı bir referans olarak hizmet etmesi için disiplinli bir yapı ve hedef kitle konusunda açık bir farkındalık gerektirir.
Problemi net bir şekilde tanımlayın ve ortaya koyun: Uygulama detaylarına girmeden önce genel bakış ve hedefler bölümlerini taslak haline getirin. Kısa, tek paragraflık bir problem tanımı, dokümantasyona hazır olunduğunu gösterir; problem net bir şekilde özetlenemiyorsa, tasarımın taslağa geçmeden önce daha fazla iyileştirmeye ihtiyacı vardır.
Dış hedef kitle için yazın: Okuyucunun planlama görüşmeleri veya alana özgü bağlam hakkında önceden bir bilgisi olmadığını varsayın. Tüm kısaltmaları ve özel terminolojiyi ilk kullanımda tanımlayın ve her kararın ardındaki gerekçeyi belirsizliği ortadan kaldıracak şekilde açıkça ifade edin.
Alternatifleri ve ödünleşimleri kaydedin: Değerlendirilen ve reddedilen seçenekleri, her karar için gerekçeleriyle birlikte belgeleyin. Bu uygulama kurumsal bilgiyi korur ve yeni ekip üyeleri sistemle etkileşime girdiğinde gereksiz tartışmaları önler.
Mimari için diyagramlara öncelik verin: Mimari ve bileşen bölümlerini akış diyagramları, sıra diyagramları veya sistem topolojisi görselleriyle destekleyin. Metni, diyagramların tek başına aktaramadığı bağlamsal açıklamalar için ayırın.
Kapsam disiplinini koruyun: Uygulama ve inceleme için gerekli tüm bilgileri ekleyin, yürütmeyi veya değerlendirmeyi etkilemeyen materyalleri hariç tutun. Kısalık, kapsamlı bir incelemenin ve kalıcı referans değerinin olasılığını artırır.
Sonuç
Teknik tasarım dokümanını sıfırdan yazmak, çoğu mühendislik ekibinin bir sprint başlamadan önce sahip olmadığı zamanı gerektirir. Her bölümü yapılandırmak, güvenlik ve testi kapsamak, ödünleşimleri belgelemek ve doğru kişilerin uygulamadan önce inceleme yapabilmesini sağlamak; tüm bu temel işlerin tek bir satır kod yazılmadan önce yapılması gerekir. Kimi Docs, bir özellik tanımından ve mevcut bağlamınızdan yapılandırılmış bir başlangıç taslağı oluşturur; böylece ekip bu zamanı doküman yerine kararlara harcayabilir.