Aynı işe gelen teklifler neden kat kat farklı? Yazılım şartnamesi nasıl yazılır

Aynı dokümanı beş firmaya gönderip aralarında kat kat fark olan teklifler alıyorsanız sorun genelde firmaların fiyat politikası değil, her birinin farklı bir işi tahmin etmesidir. Şartnamenin görevi geliştiriciye nasıl kod yazacağını anlatmak değil; hangi sonucun istendiğini, o sonucun gerçekleştiğinin nasıl doğrulanacağını ve kapsamın dışında ne kaldığını yazılı hale getirmek. Bu üçü yazılmadığında risk ortadan kalkmaz, sadece görünmez olur: teklif düşük gelir, fatura kapsam değişikliği kalemleriyle sonradan büyür. İyi haber, bir şartnameyi kıyaslanabilir hale getirmek için gereken şeylerin çoğu teknik değil, cümle düzeyinde bir disiplin meselesi.

Tekliflerdeki asıl değişken belirsizliktir

Bir teklif hazırlayan firma, okuduğu her belirsiz cümle için bir karar verir: ya kötü senaryoyu varsayıp fiyata risk primi ekler, ya da iyi senaryoyu varsayıp düşük teklif verir. İkinci grup ihaleyi kazanır. Sonra iki taraf, "kullanıcı yönetimi" cümlesinin rol tanımlama ekranını da kapsayıp kapsamadığını tartışmaya başlar.

Bu yüzden şartname kalitesi bir doküman estetiği konusu değil, doğrudan tekliflerin kıyaslanabilirliği konusudur. Tahmin isterken verdiğiniz bilginin tahmini nasıl etkilediğine dair saha araştırmasını yazılım tahmini yazısında ele aldık; oradaki sonucun şartname tarafındaki karşılığı şu: firmaya ne kadar az bilgi verirseniz, elinize gelen sayı o kadar çok o firmanın varsayımını, o kadar az sizin işinizi anlatır.

Tek bir gereksinim neye benzer

Gereksinim mühendisliğinin uluslararası standardı ISO/IEC/IEEE 29148:2018, tek bir gereksinimin taşıması gereken dokuz özellik sayıyor: gerekli, tek konulu, doğrulanabilir, tek anlamlı, tam, uygulanabilir, doğru, uygun soyutlama düzeyinde ve standart bir biçimde yazılmış. Aynı standart cümle için bir de şablon veriyor: koşul, özne, eylem, nesne ve eylemin kısıtı. Türkçede pratik karşılığı şuna benziyor: "Sipariş oluşturulduğunda sistem, sipariş onay e-postasını müşteriye en fazla 60 saniye içinde gönderir."

Listede en çok atlanan iki madde "tek konulu" ve "uygun düzeyde". Tek konulu olmak, bir cümlede iki gereksinim taşımamak demek; "sistem raporu üretir ve e-posta ile gönderir" cümlesi kabul aşamasında yarısı çalışan bir teslim üretir. Uygun düzeyde olmak ise çözümü dikte etmemek: "PostgreSQL 16 kullanılacaktır" bir gereksinim değil, bir tasarım kararıdır. Şartnameye yazarsanız daha iyi bir alternatifi olan firma o teklifi veremez. Gerçek bir kısıt varsa (mevcut ERP yalnızca MSSQL üzerinde çalışıyor gibi) elbette yazılır, ama kısıtlar bölümüne ve gerekçesiyle. 29148'in bu konuda rahatlatıcı bir yanı da var: standart, klasik "shall" cümleleri yerine kullanıcı hikayeleriyle yazmayı da kabul ediyor. Biçim serbest, doğrulanabilirlik değil.

Şartnamede kelime kokuları

Henning Femmer ve arkadaşlarının Journal of Systems and Software'de yayımlanan çalışması, 29148'in özelliklerini tersine çevirip dokuz "gereksinim kokusu" tanımlıyor. Metinde bulunması kolay olduğu için pratik bir tarama listesi: üstünlük ifadeleri (en hızlı, mümkün olan en iyi), karşılaştırmalar (daha kullanışlı, geliştirilmiş), öznel dil (kullanıcı dostu, modern, sade), kaçamak ifadeler (gerekirse, uygun olduğu ölçüde, mümkünse), belirsiz zarf ve sıfatlar (hızlıca, yaklaşık, yeterli), olumsuz kurulmuş cümleler, belirsiz zamirler (bu, onlar), açık uçlu doğrulanamaz terimler (vb., ve benzeri, gibi) ve eksik referanslar (hangi doküman, hangi sürüm).

Bu listeyi kontrol listesi gibi kullanmak yerine tek bir soruya indirgeyebilirsiniz: bu cümlenin gerçekleştiğini nasıl ölçeceğim? Cevabı yoksa elinizdeki cümle gereksinim değil, temennidir. "Arayüz kullanıcı dostu olacaktır" maddesi kabul toplantısında iki tarafın hafızasına kalır ve o toplantıda kazanan taraf, sözleşmeyi daha dikkatli okumuş olan taraftır.

Zorunlu ile tercih arasındaki çizgiyi siz çizin

Standart yazımında bu ayrım katıdır. ISO/IEC Direktifleri Bölüm 2'ye göre "shall" zorunluluk bildirir ve sapma varsa uyum iddia edilemez, "should" öneridir, "may" izindir. Şartnamelerde bu ayrım genelde hiç yapılmıyor; her madde aynı kiplerle yazılıyor ve karşı taraf hepsini zorunlu kabul ediyor. Sonuç, olmasa da olacak on maddenin fiyatı şişirmesi.

Çözüm basit: dokümanın başına bir kip sözlüğü koyun ve tutarlı kullanın. "Gönderir, sağlanır, doğrular" zorunlu; "tercih edilir" öneri; "yapılabilir" izin. Öncelik etiketi de kullanacaksanız etiketi maddenin yanına yazın, ayrı bir tabloya değil; ayrı tablo ilk revizyonda maddelerle uyumsuz hale gelir. Öncelik listelerinin neden tek başına yetmediğini MVP kapsamı yazısında ayrıntılandırdık.

Sayı içermeyen kalite gereksinimi yoktur

Fonksiyonel maddeler genelde bir biçimde yazılır, kalite gereksinimleri ise "sistem hızlı ve güvenli olacaktır" satırında kalır. Bu satır ölçülemez, dolayısıyla kabul edilemez. ISO/IEC 25010'un 2023 revizyonu bu tarafta iyi bir başlık listesi sunuyor: işlevsel uygunluk, performans verimliliği, uyumluluk, etkileşim yeteneği, güvenilirlik, güvenlik, bakım yapılabilirlik, esneklik ve emniyet. Revizyonda kullanılabilirlik "etkileşim yeteneği", taşınabilirlik ise "esneklik" olarak yeniden adlandırıldı; emniyet (safety) ayrı bir karakteristik olarak eklendi.

Bu dokuz başlığı gezip her biri için ya ölçülebilir bir hedef yazın ya da "bu projede hedef tanımlanmadı" deyin. İkincisi de geçerli bir cevap, önemli olan kararın yazılı olması. Somut haliyle: "ürün listeleme sayfası 200 eşzamanlı kullanıcı altında p95 800 milisaniye içinde yanıt verir", "planlı bakım dışında aylık kullanılabilirlik yüzde 99,5", "yedekten geri dönme süresi en fazla 4 saat". Hedefleri seçme ve ölçme mekaniği için SLO ve hata bütçesi yazısına bakabilirsiniz. Erişilebilirlik de bu gruba girer ve artık bazı sektörlerde yasal bir taban var, WCAG uyumu yazısında tarihler ve seviyeler duruyor.

Kabul ölçütü, gereksinimin bittiği yerde başlar

Bir maddenin ne zaman "tamam" sayıldığını yazmıyorsanız o kararı teslim gününe bırakmış olursunuz. En pratik kalıp, Dan North'un 2006'daki "Introducing BDD" yazısıyla yayılan üçlü: verili durum, eylem, beklenen sonuç. Chris Matts ile birlikte bu kalıbı iş analizi tarafına taşımalarının sebebi de buydu; ölçüt, geliştirici için test senaryosu, iş birimi için kabul cümlesi oluyor.

Örnek: verili durum, müşterinin sepetinde stoğu tükenmiş bir ürün var. Eylem, ödeme adımına geçer. Beklenen sonuç, o satır uyarıyla işaretlenir, sipariş oluşturulmaz ve sepetteki diğer ürünler korunur. Üç satır, tek bir kabul kararı. Şartnamelerin çoğu yalnızca mutlu yolu anlatır; asıl maliyet sınır durumlarında birikir. Stok yetmezse, ödeme yarıda kalırsa, aynı form iki kez gönderilirse ne olacağını yazmak, sonradan açılacak onlarca destek kaydını baştan kapatır.

Tahminin en çok şaştığı yer: entegrasyonlar ve veri

Şartnamelerin en zayıf bölümü genelde entegrasyonlar oluyor. "ERP ile entegre çalışacaktır" cümlesi teklif verenin gözünde bir hafta da olabilir, üç ay da. Her entegrasyon için şu satırlar yazılırsa belirsizlik büyük ölçüde biter: karşı sistem ve sürümü, erişimi kim veriyor, test ortamı var mı, kimlik bilgilerini kim sağlıyor, hız sınırı ve kota ne, veri hangi yönde akıyor, karşı sistem yanıt vermediğinde beklenen davranış ne. Bu maddelerin çoğunun cevabını siz de bilmiyor olabilirsiniz; bilmediğinizi yazmak da bir bilgidir ve teklifi keşif fazına böler.

Veri tarafı aynı şekilde. Eski sistemden taşınacak veri varsa hacmi, kaç yıllık geçmişi kapsadığı, veri kalitesinin kimin sorumluluğunda olduğu ve mükerrer kayıtlarda kararın kime ait olduğu şartnamede durmalı. Eski sistemi yenilerken veri semantiğinin nasıl bir maliyet kalemine dönüştüğünü kademeli yenileme yazısında anlatmıştık.

Kapsam dışı listesi, dokümanın en değerli sayfası

Ne yapılacağını yazmak kolaydır, ne yapılmayacağını yazmak deneyim gerektirir. "Mobil uygulama bu kapsamda değil", "çok dillilik ilk sürümde yok", "muhasebe entegrasyonu ikinci fazda", "eski sistemdeki 60 rapordan yalnızca listede sayılan 12'si taşınacak" gibi cümleler, kabul aşamasındaki tartışmaların büyük kısmını baştan kapatır.

Aynı sayfaya sözleşmenin kenarında kalan işleri de yazın: kullanıcı eğitimi kimin işi, içerik ve ürün verisi girişini kim yapacak, yayına alma günü kim nöbetçi, hangi süre boyunca hata düzeltmesi ücretsiz. Bu maddeler yazılmadığında ikisi de olur: firma bunları hesaba katmaz, müşteri de dahil sanır.

Değişikliği yasaklamayın, mekanizmasını yazın

Kapsamı dondurmak diye bir şey yok. Şartname belirli bir günde yazıldı, ihtiyaç değişecek, öğrendikçe fikriniz de değişecek. Yazılması gereken şey değişikliğin yasağı değil, yolu: talep kime iletilir, ne kadar sürede fiyatlanır, hangi büyüklüğün altındaki değişiklikler mevcut kapsam içinde kabul edilir, karar kimin imzasıyla verilir.

Bu mekanizmanın maliyeti seçtiğiniz sözleşme modeline göre değişir; sabit fiyatta her değişiklik bir müzakere, zaman-malzemede bir öncelik kararıdır. İki modelin riski nasıl dağıttığını sabit fiyat mı zaman-malzeme mi yazısında karşılaştırdık.

Teslim tanımı ekranlardan fazlasını içerir

Kabul ettiğiniz şey çalışan bir arayüzden ibaret değil. Şartnamede teslim tanımı olarak şunlar sayılmalı: kaynak kodun teslim biçimi ve hak devri, otomatik testler ve hangi düzeyde kapsama beklendiği, ortamların kurulumu, veritabanı şeması ve göç dosyaları, çalıştırma dokümanı, izleme ve alarm kurulumu, devir toplantısı. Hak devri konusunda sözleşme diline ihtiyacınız varsa kaynak kod mülkiyeti yazısı bu kısmı kapsıyor, test kapsamı beklentisini nasıl yazacağınız için de test otomasyonu yazısına bakın.

Buraya konabilecek en işe yarar kabul maddesi şudur: projeyi devralan yeni bir geliştirici, yalnızca depodaki dokümanı okuyarak ortamı ayağa kaldırabilir ve testleri çalıştırabilir. Bu maddeyi kabul kriteri yapan ekipler, devir sonrası ilk ayı bilgi arkeolojisiyle geçirmiyor.

Taslağı modele yazdırmak işe yarar, ama sınırı belli

Dil modelleri boş sayfa problemini gerçekten çözüyor: iskeleti çıkarır, aklınıza gelmeyen başlıkları hatırlatır, dağınık notları maddeye çevirir. Yapamadığı şey sizin süreçlerinizi bilmek. Üretilen taslaklarda en sık görülen kusur, doğrulanabilir görünen ama içinde sizin işinize ait tek bir sayı bulunmayan cümleler oluyor.

Pratik yöntem: taslağı modelden alın, sonra yukarıdaki koku listesiyle tarayın ve her kalite maddesinin yanına kendi sayınızı yazın. Aynı disiplinin kod tarafındaki hali için AI ile yazılan kodu gözden geçirme yazısına bakabilirsiniz.

Bu haftaya sığan ilk adım

Elinizde bir şartname varsa iki geçiş yapın. Birinci geçişte doğrulanamayan her cümleyi işaretleyin, ikinci geçişte her işaretli cümleye ya bir sayı ya bir kabul ölçütü ekleyin; ekleyemiyorsanız o madde kapsam dışı listesine ya da keşif fazına gider. Sonra tek sayfalık kapsam dışı bölümünü yazın, genelde en hızlı geri dönen yatırım orada.

Şartnameniz yoksa 20 cümlelik bir sonuç listesiyle başlayın ve bunu taslak olduğunu belirterek teklif isteyeceğiniz firmalara gönderin, karşılığında soru listesi isteyin. Gelen sorular iki şeyi birden ölçer: sizin dokümanınızdaki boşlukları ve karşı tarafın işi gerçekten okuyup okumadığını. Hiç soru sormayan firmanın teklifi, en dikkat etmeniz gereken tekliftir.