Uzaktan mühendislik ekipleri için ücretsiz dokümantasyon aracı

Trupeer AI, yan yana oturup hemen soramayan uzaktan mühendislik ekipleri için yürütüm (walkthrough) dokümantasyon aracıdır. Kıdemli bir mühendis açıklamayı bir kez kaydeder (deploy pipeline’ın gerçekte nasıl çalıştığı, bu hizmetin neden denemeleri (retries) bu şekilde ele aldığı, kod tabanındaki “zorlu” kısmın ne yaptığı ve neden bu kadar zorlu olduğu) ve Trupeer AI aynı işte hem bir video hem de yazılı bir mühendislik dokümanı üretir. Farklı zaman dilimlerinde ve farklı ofislerde çalışan diğer mühendisler içeriği eşzamansız (async) olarak izler ve okur. Dağıtık mühendislik ekipleri READMEs eksikliğinden çok, README’nin arkasındaki açıklamanın eksikliğinden muzdarip olur; bu açıklama kıdemli bir mühendisin bir öğleden sonrasını alır ve kimsenin ayıracak bant genişliği yoktur.

• Kıdemli mühendis yürütümü kaydeder. Video ve yazılı mühendislik dokümanı birlikte gelir.

• Zaten yaşadıkları eşzamansız, çok zaman dilimli çalışma akışına göre tasarlandı.

• ABD, Hindistan, Avrupa ve LATAM genelinde mühendislik ekipleri için 65+ dile dokümantasyon çevirisi yapar.

• Ekipteki mevcut wiki, kod deposu ve API dokümanlarının yanında konumlanır. Hiçbirinin yerini almaz.

• Değişen adımı yeniden kaydederek güncelleyin. Mimariyi anlatan açıklama güncelliğini yitirmez.

Trupeer AI’nin mühendislik ekipleri için ürettikleri

Kıdemli bir mühendis bir ekran kaydı açar. Üretim servisini dağıtmayı, staging ortamını hata ayıklamayı ya da ekibin 2024’te aldığı mesaj kuyruk tasarım kararını açıklamayı adım adım anlatır. Trupeer AI post-prodüksiyonu yönetir. Dolgu sözcükler gider. Yakınlaştırma efektleri, bir sonraki mühendisin bakması gereken terminal komutunu, IDE bölgesini veya kontrol panelini öne çıkarır. Taslak video ve taslak yazılı mühendislik dokümanı aynı yerde; ekran görüntüleri ve numaralı adımlar satır içi olarak görünür.

Çıktılar MP4 video ve PDF ya da Word dokümanı olarak teslim edilir. Doküman, birinin wikide okuduğu ya da Notion veya Confluence’a yapıştırdığı şeydir. Videolar ise birinin yardım merkezinde izlediği, Linear biletine gömülü olarak kullandığı ya da Shared Page bağlantısı üzerinden paylaştığı içeriklerdir. İkisi de aynı kayıttan gelir; ikinci bir tur yoktur. Marka kit’i, mühendislik ekibine özel giriş ve kapanış slaytlarını uygular; özel sözlük ise AI’nin aksi halde doğru yazamayabileceği dahili servis adlarını, altyapı bileşeni adlarını ve kısaltmaları yönetir.

Mühendislik dokümantasyon aracı üç adımda nasıl çalışır?

Üç adım tüm akışı kapsar: kıdemli mühendisin kafasında zaten yaptığı şeyi kaydedin, AI’nin iki formatı da üretmesine izin verin ve zaman diliminden bağımsız olarak ekibin geri kalanının bulabileceği bir bağlantı üzerinden paylaşın.

Adım 1: Açıklamayı kaydedin

Tarayıcıda, mühendislik ekibinin IDE’sinde veya terminal üzerinden ekran kaydı başlatın. Kıdemli mühendis, yeni işe başlayan kişiyle 1:1 görüşmede nasıl anlatırsa aynı şekilde çalışmayı seslendirir. Mimariyi anlatan bir açıklama ya da bir dağıtım (deployment) yürütümü için genellikle 5 ila 10 dakikalık kayıt yeterlidir. AI, kaydedileni temel alarak çalışır; bu nedenle kıdemli mühendisin taslak yazması ya da slayt hazırlaması gerekmez.

Adım 2: AI video ve yazılı mühendislik dokümanını üretir

Dolgu sözcükler ve “şu dosyayı bulmama izin ver” gibi anlar kaldırılır. Yakınlaştırma efektleri, ekranın önemli kısımlarını öne çıkarır (dosya yolu, terminal çıktısı, PR incelemesindeki diff). Taslak video ve taslak yazılı mühendislik dokümanı editörde birlikte görünür. Özel sözlük, dahili servis adlarını ve bileşen kısaltmalarını yanlış transkribe edilmeden önce yakalar.

Adım 3: Markalayın, çevirin, paylaşın

Ekip kütüphanenizdeki mühendislik içi dokümanların ekip genelinde tutarlı görünmesi için marka kit’i uygulayın. Çevirin: ekiplerin gerçekten çalıştığı dillere. Mexico City ofisi için İspanyolca, Bangalore ekibi için Hintçe, São Paulo ekibi için Portekizce. Wikide yaşayan bir Shared Page bağlantısı üzerinden gönderin; ekibin onboarding dokümanında yer alsın ya da mühendislerin akışı bozmadan bulabileceği şekilde doğrudan Slack thread’lerine yapıştırın.

Bu mühendislik dokümantasyon aracını kim açar?

Bu aracı açan kişi genellikle bir staff engineer, bir mühendislik yöneticisi (engineering manager) ya da uzaktan-first ya da hibrit bir mühendislik organizasyonunda, en az iki zaman diliminde insanları olan bir tech lead olur. Yeni bir kişi ekibe katıldığında ve README tek başına yeterli olmadığında, ekibin kaydedilmeye değer ve gerekçesi kayda değer bir “kolay anlaşılmayan” mimari kararı olduğunda ya da nöbet (on-call) runbook’ının sadece komutları listelemek yerine 3am’de ne yapılacağını gerçekten açıklaması gerektiğinde açarlar. Bazı ekipler bunu her büyük tasarım kararı için rutin olarak kullanır; diğerleri ise açıklama şeklindeki boşluk ortaya çıktığında yalnızca o zaman başvurur.

Aynı iş akışı roller boyunca da görülür. DevOps ve SRE liderleri, daha geniş mühendislik organizasyonuyla paylaşılan incident retros ve altyapı yürütümlerini kaydeder. Mühendislik yöneticileri, her hafta DM’lerde aynı soruların tekrar tekrar sorulmaması için yeni işe başlayanlar için onboarding yürütümlerini kaydeder. Tech lead’ler, gelecekteki mühendislerin bir sistemin neden bu şekilde göründüğünü bilmesi için mimari kararları kaydeder. Engineering başkanları (heads of engineering), aksi halde 50 kişilik ve kimsenin katmak istemeyeceği bir tüm ekip toplantısı gerektirecek çapraz ekip (cross-team) yayılımlarını (yeni bir dahili platform, bir servis migrasyonu, deploy sürecine bir değişiklik) kaydeder.

Bu araç hangi içerik türlerini yönetir?

En sık karşılaşılan içerik türleri şunlardır: mimari ve tasarım yürütümleri (bu sistem neden böyle görünüyor), dağıtım ve altyapı runbook’ları (üretime nasıl gönderilir, nasıl geri alınır), onboarding yürütümleri (kod tabanı turu, yerel geliştirme kurulumu, ilk PR yürütümü), incident retros ve post-mortem’ler (ne oldu, ne öğrendik, neyi değiştiriyoruz) ve kod inceleme açıklayıcıları (anlaşılması kolay olmayan bir PR’ın arkasındaki “neden”). Trupeer AI bunların hepsini aynı kayıt-ile-doküman akışıyla yönetir. Format uyarlanır: bir runbook numaralı adımlar ve ekran görüntüleri ister; bir mimari açıklayıcı yazılı özetle birlikte videoyu ister; bir onboarding turu ise ikisini birden ister.

Daha geniş anlamda mühendislik dokümantasyonu için Trupeer AI, yalnızca metin tabanlı wiki araçlarının boş bıraktığı açıklama (explainer) katmanını doldurur. Yazılım mühendisliği dokümantasyonu genellikle üç katmana ayrılır: kod tarafından üretilen referans dokümanlar (Sphinx, javadoc, OpenAPI), ekip wiki içeriği (Confluence, Notion, Slab) ve insan tarafından kaydedilen yürütümler. Çoğu mühendislik ekibinde ilk katman vardır; çünkü otomatik çalışır. İkinci katman da vardır; çünkü birine bunu yazması için ödeme yapılmıştır. Üçüncü katman (yazılım mühendisliğinde sistem dokümantasyonu, mühendislik proje dokümantasyonu, yazılım mühendisliğinde dahili dokümantasyon) ise her zaman geride kalır. Trupeer AI, bu üçüncü katmanı üretmeyi o kadar hızlandırır ki kıdemli bir mühendis bunu toplantılar arasında bir Cuma öğleden sonrasında yapabilir.

Trupeer, wiki’ler, kod-doc araçları ve API dokümantasyon üreticilerinin yanında nereye oturur?

Trupeer AI, ekibin wikisi’nin yerini almaz. Confluence, Notion, Slab, GitBook ve dahili ekip wiki’si kendi işlerini yapmaya devam eder. Trupeer AI, bu wikilere Shared Page olarak gömülen kayıtlı açıklayıcı içerikleri üretir; ekibin zaten yazdığı yazılı makalelerin yanında yer alır.

Trupeer AI ayrıca API dokümantasyon üreticilerinin yerini almaz. Swagger, Stoplight, Redoc, Postman ve otomatik üretilen herhangi bir OpenAPI referans, endpoint seviyesindeki referans dokümanları yönetmeye devam eder. Trupeer AI farklı bir katmanda konumlanır: API’nin nasıl tasarlandığının, ona karşı gerçekten nasıl entegre olunacağının ve referans dokümanların ortaya çıkarmadığı “tuzakların” insan tarafından anlatıldığı yürütüm. Bir mühendislik ekibinin dokümantasyon kütüphanesi tipik olarak ikisini de ister: otomatik üretilen referansı ve insan tarafından kaydedilen açıklayıcıyı. Trupeer AI yalnızca ikincisini yönetir; ilki bulunduğu yerde kalır. Aynı mantık, Doxygen, javadoc ve satır içi yorum sistemleri gibi kod seviyesindeki araçlar için de geçerlidir; Trupeer AI bunlarla rekabet etmek yerine tamamlar. Daha geniş anlamda mühendislik dokümantasyonu yönetimi ve teknik dokümantasyon için bu, ekibin elindekini sökmeden bir açıklama katmanı eklemesi anlamına gelir.

Küresel olarak dağıtık mühendislik ekipleri için güncellemeler ve çeviri

Mühendislik dokümantasyonu, mühendislik dışı ekiplerin beklediğinden daha hızlı bozulur; çünkü altta yatan sistemler haftalık olarak değişir. Bir deploy pipeline değişikliği geçen çeyreğin runbook’unu bozar, bir mimari refactor tasarım dokümanını yanıltıcı hale getirir, yeniden adlandırılan bir servis onboarding yürütümünü kafa karıştırıcı yapar. Çoğu ekip bunu, dokümanların sessizce güncelliğini yitirmesine izin verip herkes artık eski dokümana denk geldiğinde Slack’te soruları yanıtlayarak yönetir. Trupeer AI güncellemeleri, yalnızca değişen bölümü yeniden kaydederek yapar. AI yalnızca o kısmı yeniden işler; video ve yazılı mühendislik dokümanı aynı yerde güncellenir ve wikiyi bir sonraki açan kişi güncel sürümü görür.

Küresel olarak dağıtık mühendislik ekipleri için çeviri, standup’ta kimsenin bahsetmediği sürtüşmeyi azaltır. Aynı mimari açıklayıcı, aynı kaynak kayıt üzerinden aynı hafta içinde Bangalore ekibine Hintçe, Berlin ekibine Almanca ve São Paulo ekibine Portekizce olarak ulaşır. Çeviri, video seslendirmesi ve yazılı mühendislik dokümanı için de geçerlidir; marka kit’i, sözlük ve ekrandaki metinler boyunca taşınır. Bu mühendislik ekibi dokümantasyon iş akışını Trupeer AI SOP builder ile eşleştirmek, mühendislik odaklı yürütümleri ve mühendislik ekiplerinin organizasyonun diğer bölümlerine devrettiği çapraz fonksiyonel standart işletim prosedürlerini (SOP) birlikte kapsar.