Çalışma Biçimini Yazıya Dökmek: Olgun Bir Mühendislik Ekibinin Sahiplendiği Belgeler

Çoğu ekip çalışma biçimini insanların kafasında tutar. Sonuç tahmin edilebilir: her yeni katılan kişi “biz işleri nasıl yaparız” konusunun farklı ve eksik bir versiyonunu öğrenir, beklentiler hiç yazılmadığı için nöbet stresli geçer ve kilit bir kişi ayrıldığında aylarca biriken bağlamı yanında götürür. Çözüm “daha fazla belge yazmak” değildir; çözüm, çalışma biçimini her biri tek bir sahibe ait, işin yanında saklanan, küçük ve adı konmuş bir canlı belge kümesi olarak ele almak ve onboarding’i bir refakatçi ritüeli yerine takip edilen, kontrol listeli bir program olarak yürütmektir. Devamı, sağlıklı bir ekibin sahiplendiği belirli belgelerin bir taksonomisi ve her birini iyi yapan şeyin yaygın başarısızlık biçimine karşı duruşudur.

Konu API belgeleri ya da mimari referanslar değildir; o bilgi kalıcılığı katmanı bilgiyi ölçekleyen altyapı olarak dokümantasyon yazısında ele alınıyor. Bunun üzerindeki katman, bir ekibin nasıl çalıştığına, nasıl katıldığına ve devri nasıl yaptığına dair insan odaklı operasyon el kitabıdır.

Belge Haritası

Olgun bir ekip dağınık bir wiki değil, adı konmuş bir avuç belge sahiplenir. Her biri farklı bir soruyu yanıtlar ve her birinin bir sahibi vardır. Aşağıdaki harita yazının tamamını tek bir resimde gösterir: altı belge türü, her birinin yanıtladığı soru ve onu kim canlı tutar.

Yazının geri kalanı her birini tek tek inceliyor: ne olduğunu, iyi versiyonunun nasıl göründüğünü ve yerini aldığı başarısızlık biçimini.

Takip Edilen Bir Program Olarak Onboarding

İşe yarayan varsayılan, onboarding’i gölge gibi takip edilecek bir kişi olarak değil, takip edilen biletler olarak kurgulamaktır. Her bilgi alanı için bir alt bileti olan, her biri zaman kutusuna alınmış ve atanmış bir üst epic düşünün: ekibe giriş, mimari genel bakış, çalışma biçimi (toplantılar ve panolar), takım anlaşmaları, Definition of Done, geliştirme yaşam döngüsü, dağıtım ve izleme, erişim talepleri. Belirli roller bunu taşır: bir takım lideri programın sahibidir, bir mentor soruları yanıtlar ve yeni katılan kişi (mentee) listeyi adım adım tamamlar. Program, birinin yerleştiğine dair belirsiz bir his yerine ölçülebilir bir “hazır” durumu üretir.

Başarısızlık biçimi refakatçi ritüelidir: “iki hafta birini takip et.” Kimin boş olduğuna bağlıdır, her seferinde farklıdır ve bir tamamlanma sinyali yoktur. Yeni katılan kişinin gerçekten hazır olup olmadığını kimse söyleyemez, çünkü “hazır”ın ne anlama geldiğini hiçbir şey takip etmemiştir.

Bir zamanlama tuzağı da var. Google’ın re:Work rehberi onboarding’i “günler değil, aylar süren” bir süreç olarak çerçeveler ve birden fazla kez yoklama yapmayı önerir: yeni çalışanlara 30, 90 ve 365. günlerde üç alanda anket uygulamak, “1) teknoloji ve araçlar, 2) verimlilik ve beceriler ve 3) kültür ve bağ.” Beşinci günde biten bir ilk hafta kontrol listesi, onboarding’in büyük kısmını kaçırır. Programı ilk çeyreğe yayacak şekilde kurun ve yeni katılan kişinin ilk pull request’ini onboarding belgesinin kendisine yapılan bir iyileştirme yapın. Bu tek alışkanlık belgeyi canlı tutar, çünkü eksiklerin en çok farkında olan kişi onları tazeyken düzeltir.

Ödünleşim. Takip edilen bir program başta yazma ve bakım zamanına mal olur; ayrıca eski bir kontrol listesi hiç olmamasından kötüdür, çünkü yanlış şeyi otorite havasıyla öğretir. “İlk PR onboarding’i iyileştirir” kuralı bu maliyeti geri öder; bir sahip ve geri bildirim döngüsü yoksa, töreni atlayıp kısa bir README’de kalın.

Takım Çalışma Anlaşmaları

Çalışma anlaşmaları, bir ekibin kendisi için belirlediği açık normlardır: toplantı sıklığı, çekirdek saatler, kod incelemesi yanıt süresi, hangi kanalın ne için olduğu ve kararların nasıl alındığı. İyi versiyonu kısa, belirli ve gözlemlenebilirdir. “Açık pull request’leri bir iş günü içinde inceleriz” bir anlaşmadır; “iş birliğine değer veririz” bir afiştir.

Apaçık olmayan özellik sahipliktir. Anlaşmalar ekip tarafından yazılmalıdır, yukarıdan dayatılmamalıdır. Atlassian’ın Working Agreements play’i, bunların “zaman içinde güncellenebilen ve güncellenmesi gereken bir başlangıç noktası” olduğunu açıkça söyler; üç ayda bir, yeni üyeler katılırken, yeniden yapılanmalarda ya da “bir anlaşma artık sürdürülemez hale geldiğinde” gözden geçirilmeli ve ekip her birini korumak ya da değiştirmek için oy vermelidir. Bir anlaşma yukarıdan dayatıldığı an, ekibin nasıl çalıştığını tarif etmeyi bırakır ve birinin nasıl çalışmasını dilediğini tarif etmeye başlar.

Kod incelemesi normları bu belgede kendi satırını hak eder, çünkü “nasıl çalıştığımızın” çoğu aslında incelemede yaşar; kılı kırk yarmak ile bilgi paylaşımı arasındaki fark, açıkça yapılmaya değer kültürel bir tercihtir ve kod incelemesi kültürü yazısında ele alınıyor.

Ödünleşim. Anlaşmaları belirli aralıklarla gözden geçirmek gerçek ve tekrar eden bir iştir; hiç gözden geçirmeyen bir ekip ise kendi davranışıyla çelişen bir belgeyle kalır. Buna karşılık, her etkileşimi aşırı belirlemek süreç tiyatrosuna dönüşür. Listeyi, yazılmadığında gerçekten sürtünme yaratan birkaç norma sınırlı tutun.

Definition of Done

Definition of Done, “bitti”nin ne anlama geldiğine dair ortak ve yazılı kontrol listesidir: testler yazıldı, incelendi, belgeler güncellendi, dağıtıldı, gözlemlenebilir. Scrum Guide 2020 bunu “Increment’in, ürün için gereken kalite ölçütlerini karşıladığı durumun resmi bir tanımı” olarak adlandırır ve şunu belirtir: “hangi işin tamamlandığına dair herkese ortak bir anlayış sağlayarak şeffaflık yaratır” ve geliştiriciler “Definition of Done’a uymakla yükümlüdür.” Scrum uygulamayan ekipler bile bu çerçeveden faydalanır: tek, görünür ve kanonik bir “bitti”, aksi halde inceleme sonrasına hata sızdıran kişiye özel bir pazarlığı ortadan kaldırır.

Başarısızlık biçimi örtük bir Definition of Done’dur; bu, “bitti”nin teslim baskısı altında her mühendisin verdiği karar olması demektir. Birinin “bitti”si merge edilmiştir; bir başkasınınki dağıtılmış ve canlıda doğrulanmıştır. Bu iki tanımın arasındaki boşluk, regresyonların yaşadığı yerdir.

Adı konmaya değer verimli bir gerilim var. Scrum, Definition of Done’u geliştiricilerin uymak zorunda olduğu resmi bir taahhüt olarak ele alır; Kanban ve sürekli akış ekipleri ise sıklıkla daha hafif, evrilen bir “bitti” tutar. Her iki taraf da tanımın yazılı ve paylaşılmış olması gerektiğinde hemfikirdir. Yalnızca biçimsellik konusunda ayrışırlar ve bu tercih dogmayı değil, ekibin olgunluğunu takip etmelidir. Yeni bir ekip katı bir kontrol listesinin disiplininden faydalanır; yüksek güvenli bir ekip daha hafif bir tanesini güvenle çalıştırabilir.

Ödünleşim. Katı bir Definition of Done, onu aşmış bir ekibi yavaşlatabilir; bir kalite kapısını bürokratik bir damgaya dönüştürür. Çözüm, belgenin ilk gün yazılan versiyonda donmasına izin vermek yerine ekiple birlikte evrilmesine izin vermektir.

Nöbet ve Olay Beklentileri

Nöbet genellikle bir takvim olarak vardır. Eksik olan beklentilerdir: önem seviyeleri, eskalasyon yolu, yanıt süresi hedefleri, devir prosedürü, runbook’lar ve suçlamasız bir postmortem şablonu. İyi versiyonu bunları olaydan önce yazıya döker, böylece kimse en kötü anda önem seviyesini pazarlık etmez.

Google’ın SRE kitabı yanıt süreleri için faydalı bir çapa koyar: bunlar “ekip ve iş sistemi sahipleri tarafından üzerinde anlaşılır” ve “tipik değerler” şöyledir: “kullanıcıya dönük ya da başka türlü oldukça zaman kritik servisler için 5 dakika ve daha az zaman duyarlı sistemler için 30 dakika.” PagerDuty’nin olay müdahale rehberi insan gerçeği konusunda aynı ölçüde nettir: ekip alarm eskalasyonunun “5 dakika içinde gerçekleştiğini” ve nöbetçi bir mühendisin “sabahın ikisinde bile sorunlara yanıt verebilmesinin beklendiğini” belirtir. Bu beklentileri yazıya dökmek, rotasyonu kahramanlığa dayalı olmaktan çıkarıp sürdürülebilir kılan şeydir; SRE kitabı, nöbet stresini azaltmanın mühendisleri panikleyen değil, bilinçli karar vermede tuttuğunu açıkça söyler.

Postmortem yarısı da en az o kadar önemli. Google’ın rehberini doğrudan alıntılamaya değer: “Bir postmortem’den suçlamayı kaldırmak, insanlara sorunları korkmadan eskale etme güvenini verir” ve “suçlama atmosferi, olayların ve sorunların halının altına süpürüldüğü bir kültür yaratma riski taşır.” Ayrıca postmortem ölçütlerini bir olaydan önce tanımlamayı vurgular: “böylece herkes bir postmortem’in ne zaman gerekli olduğunu bilir.” Suçlamasız, önceden tanımlanmış bir süreç, bir olaydan ders almak ile onu saklamak arasındaki farktır.

Başarısızlık biçimi, nöbeti “kim oradaysa” olarak görmektir; runbook yoktur ve bir suçlama kültürü vardır. Kahramana bağımlıdır, insanları tüketir ve aynı olayın tekrar etmesini garanti eder, çünkü sonrasında hiçbir şey yazıya dökülmemiştir.

Ödünleşim. Runbook’lar ve postmortem’ler, sakin bir haftada masraf gibi hissettiren zaman harcar. O maliyet, sabahın ikisindeki bir çağrı runbook var diye dakikalar içinde çözüldüğünde geri ödenir. Kaçınılması gereken risk runbook çürümesidir: güncel olmayan bir runbook aktif olarak yanlış yönlendirir, bu yüzden her birine bir sahip atayın ve kullanıldıktan sonra gözden geçirin.

Katılım ve Ayrılma için Bilgi Aktarımı

Onboarding’in çoğu ekibin atladığı bir ayna görüntüsü vardır: offboarding. Birini içeri getiren aynı kontrol listesi disiplini, ayrıldığında onun bağlamını dışarı taşımalıdır. İyi bir bilgi aktarımı belgesi, ayrılan kişinin sahiplendiği sistemleri listeler, erişimi bilinçli olarak devreder, yalnızca o kişinin kafasında yaşayan örtük bağlamı kayıt altına alır ve her sorumluluk için yeni sahibi belirler.

Team Topologies burada “takım API’si” fikri, yani bir ekibin nasıl tüketildiğine dair belgelenmiş yüzey, üzerinden faydalı bir mercek sunar. Modeli şunu savunur: “bir ekibin etkileşime girebileceği yalnızca üç yol vardır: iş birliği, hizmet olarak (X-as-a-service) ve kolaylaştırma.” Nasıl tüketildiğini yazıya dökmüş bir ekip bir üyenin ayrılmasını atlatır, çünkü arayüz bireyden daha uzun yaşar. (Ekip sınırlarının bu arayüzü nasıl şekillendirdiği için ekip otonomisi yapıları yazısına bakın.)

Başarısızlık biçimi, gerçekleşmiş bus-factor riskidir: offboarding’in bir veda mesajı olması ve altı aylık bağlamın kapıdan çıkıp gitmesi. Aktarım mekaniği bu belgeye aittir; daha geniş risk ve onu nasıl ölçüp azaltacağınız bus factor ve bilgi yönetimi yazısının konusudur.

Ödünleşim. Tam bir aktarım, ayrılan kişinin özellikle kısa bir ihbar süresinde sahip olamayacağı zamanı alır. Önceliklendirin: yeniden keşfetme maliyeti en yüksek olan sistemleri önce belgeleyin ve kolayca yeniden öğrenilebilen değişken ayrıntıların dışarıda bırakılabileceğini kabul edin.

Karar Kayıtları

Önemli teknik kararların, bağlamlarının ve gerekçelerinin yazılı bir kaydına ihtiyacı vardır, böylece “neden” alındığı toplantıdan daha uzun yaşar. Bu, taksonomide zaten kendine ait bir rehberi olan bir maddedir, bu yüzden mekaniği yeniden anlatmak yerine karar kayıtlarını (ADR ve RFC) birinci sınıf bir takım belgesi olarak ele alın ve bir teknik RFC’nin anatomisi yazısındaki mevcut açıklamaya dayanın. İyi versiyonu nedeni yakalar ve kodun yakınında değişmez bir geçmiş tutar; başarısızlık biçimi, kararların sohbet dizilerine gömülmesi ve dizi kayıp gittiği an bağlamlarının yitmesidir.

İyi Bir Takım Belgesinin Özellikleri

Yukarıdaki altı belge aynı özellikleri paylaşır ve asıl argüman da bu özelliklerdir. Bir takım belgesi yerini ancak şu durumlarda hak eder:

Özellik	Anlamı	Önlediği başarısızlık
Canlı	Bir sahibi ve gözden geçirme ritmi var; eskime bir hata sayılır	Kimsenin güvenmediği wiki mezarlığı
Sahipli	”Ekip” değil, adı konmuş bir kişi	Dağılmış sorumluluk, böylece kimse güncellemez
Eyleme dönük	Okuyan biri yalnızca onaylamaz, bir şey yapabilir	Hedef gibi sunulan afişler
İşin yanında	İnsanların zaten kullandığı repo ya da araçta	Ayrı bir sistemde unutulmuş wiki
Kendi kendine yeten	Yeni katılan kişinin başlamak için eş zamanlı bir insana ihtiyacı yok	Birinin takvimine takılan onboarding
Yapılandırılmış	Her belge işini bilir (öğretici, nasıl-yapılır, referans, açıklama)	Modları karıştırıp okuyanı şaşırtan belgeler

Bu son özellik Diátaxis’ten gelir; dokümantasyonu kullanıcı ihtiyacına göre dört moda ayırır: öğretici, nasıl-yapılır, referans ve açıklama. Bunları tek bir sayfada karıştırmak, belgelerin kafa karıştırıcı hissettirmesinin yaygın bir nedenidir; bir “nasıl dağıtırım” nasıl-yapılır ile bir “neden böyle dağıtıyoruz” açıklaması farklı okurlara hizmet eder ve farklı yerlere aittir.

Tek doğruluk kaynağı (single source of truth) ilkesi geri kalanı birbirine bağlar. GitLab Handbook bu konuda nettir: içeriği tekrarlamak yerine çapraz bağlantı verin, çünkü yinelenen içerik daha fazla bakım işine yol açar ve tek bir doğruluk kaynağı yalnızca tek bir sistemde yaşar. Bu belgelerin birbirini yeniden anlatmak yerine birbirine işaret etmesinin nedeni, kopyalamak değil çapraz bağlamaktır.

GitLab ayrıca canlı belge duruşunu en uç biçimiyle modeller: “GitLab’da her şey taslak halindedir ve değişebilir, buna handbook’umuz da dahil.” Her belgeyi, herkesin bir merge request ile iyileştirebileceği bir taslak olarak ele almak, büyük bir handbook’un çürümesini önleyen şeydir. Bu, spektrumun handbook-first ucudur ve bedelsiz değildir; bu da bizi merkezi gerilime götürür.

Ne Zaman Belgelememeli

GitLab tarzı handbook-first kültürü, neredeyse her şeyi tek bir doğruluk kaynağı olarak belgelemeye iter. Yalın karşı argüman, değişken belgelerin kimsenin sürdürebileceğinden daha hızlı eskidiği ve aşırı belgelemenin bir ekibin değişme yeteneğini katılaştırdığıdır. İkisi de kendi bağlamında haklıdır ve çözüm, neyi yazıya dökeceğine dair bir kuraldır: kararlı olanı ve yeniden keşfetme maliyeti yüksek olanı belgeleyin, değişkeni atlayın. Eskime, bir sahibin düzelttiği bir hatadır, asla yazmamak için bir gerekçe değil.

Geçersiz kılma durumları ekibin durumundan doğar. Yeni ya da sıfırdan bir ekip en küçük uygulanabilir kümeyle başlamalıdır: bir onboarding kontrol listesi, bir Definition of Done ve çalışma anlaşmaları. Olaylarda zorlanan bir ekip her şeyden önce nöbet beklentilerini ve runbook’ları yazmalıdır. Dağıtık ya da asenkron bir ekip handbook-first’e doğru itmekten en çok faydayı görür, çünkü asenkron çalışma omuza dokunmaya geri dönemez. Küçük, aynı yerde ve birbirine yeterince güvenen bir ekip için repo içindeki bir README gerçekten yeterli olabilir; ona daha fazla süreç dayatmak, aşırı belgeleme başarısızlığının farklı bir kılıktaki halidir.

Yaygın Tuzaklar

Birkaç başarısızlık örüntüsü doğrudan adlandırmaya yetecek kadar sık tekrarlar. Wiki’yi doğruluk kaynağı yerine bir hedef olarak görmek en yaygınıdır: başarıyı sayfa sayısıyla değil, “yeni katılan kişi kendi kendine yetebildi mi” ile ölçün. Çalışma anlaşmalarını yukarıdan yazmak, ekibin görmezden geldiği bir belge üretir, çünkü ekip ona hiç katılmamıştır. Değişken olan dahil her şeyi belgelemek ekibi katılaştırır ve önemli olan kararlı belgeleri gürültü altında gömer. Hiç güncellenmeyen bir onboarding belgesi aktif olarak yanlışa kayar, “ilk PR onboarding’i iyileştirir” kuralının var olma nedeni budur. Ve nöbeti bir takvim olarak yazıp beklentiler olarak yazmamak, rotasyonu kimse bir şey yazmadan önce ne kadar stresliyse o kadar stresli bırakır.

Kapanış

Çalışma biçimini, işin yanında saklanan, küçük, canlı ve sahipli bir belge kümesi olarak ele alın ve onboarding’i bir refakatçi ritüeli yerine takip edilen bir program olarak yürütün. Bu varsayılan, ilk birkaç mühendisini geçmiş hemen her ekip için geçerlidir. Ekip dağıtık ve asenkron olduğunda handbook-first ucuna uzanın; ekip küçük, aynı yerde ve daha fazlasını sürdürmenin maliyetinin değerini aşacağı kadar yüksek güvenli olduğunda yalın, yalnızca README kurulumuna uzanın. Tek bir sonraki adım, getirisi en yüksek olan en ucuz olandır: onboarding’inizi gölge gibi takip edilecek bir kişiden takip edilen bir kontrol listesine çevirin ve onu iyileştirmeyi yeni katılan kişiye verdiğiniz ilk görev yapın.

Kaynaklar

• Scrum Guide 2020 — Definition of Done - Geliştiricilerin uymakla yükümlü olduğu resmi bir taahhüt olarak kanonik “bitti” tanımı.
• Google SRE Book — Being On-Call (Bölüm 11) - Çağrı yanıt süresi beklentileri (5 dk / 30 dk) ve sürdürülebilir, düşük stresli nöbet.
• Google SRE Book — Postmortem Culture (Bölüm 15) - Suçlamasız postmortem’ler ve postmortem ölçütlerini olaydan önce tanımlama.
• Atlassian Team Playbook — Working Agreements - Ekip tarafından yazılan, üç ayda bir ve yeniden yapılanmalarda gözden geçirilen, ekip oyuyla korunan ya da değiştirilen anlaşmalar.
• GitLab Handbook — Handbook Usage (Tek Doğruluk Kaynağı) - Çoğaltmak yerine çapraz bağlantı; her içerik için tek bir yetkili sistem.
• GitLab Handbook — About the Handbook (“her şey taslak halinde”) - Handbook-first kültürünün arkasındaki canlı belge duruşu.
• Team Topologies — Key Concepts - Ekip etkileşim modları ve “takım API’si”: bir ekip nasıl tüketildiğini belgeler.
• Google re:Work — Onboarding’e veri odaklı bir yaklaşım - Onboarding günler değil aylar sürer; 30/90/365. günlerde araçlar, beceriler ve kültür üzerine anket.
• PagerDuty Incident Response — Being On-Call - Somut yazılı nöbet beklentileri: hazırlık ve triyaj, 5 dakikalık eskalasyon, alarmları onaylama.
• Diátaxis - Belgeleri kullanıcı ihtiyacına göre yapılandırmak için dört dokümantasyon modu (öğretici, nasıl-yapılır, referans, açıklama).
• Camille Fournier, The Manager’s Path (O’Reilly) - Mühendislik yöneticileri ve liderler için yapılandırılmış onboarding ve kurumsal bilgi.