Uzaktan Çalışan Mühendislik Ekipleri İçin Dokümantasyon Aracı

Trupeer AI, yanındakine eğilip soru soramayacak kadar uzakta olan, uzaktan çalışan mühendislik ekipleri için adım adım ilerleyen bir kılavuz dokümantasyon aracıdır. Kıdemli bir mühendis açıklamayı bir kez kaydeder (dağıtım hattının aslında nasıl çalıştığı, bu servisin yeniden denemeleri neden bu şekilde ele aldığı, kod tabanının karmaşık kısmının ne işe yaradığı ve neden karmaşık olduğu vb.) ve Trupeer AI aynı işleme içinde hem bir video hem de yazılı bir mühendislik dokümanı oluşturur. Farklı zaman dilimlerinde ve farklı ofislerde çalışan diğer mühendisler ise bunu asenkron olarak izler ve okur. Dağıtılmış mühendislik ekipleri eksik README dosyalarından ziyade, kıdemli bir mühendisin yazması bir öğleden sonrasını alan ve hiç kimsenin bunun için vakti olmadığı, README'nin arkasındaki açıklamanın eksikliğinden muzdariptir.

• Kıdemli mühendis açıklamalı kılavuzu kaydeder. Video ve yazılı mühendislik dokümanı aynı anda hazır olur.

• Dağıtılmış mühendislik ekiplerinin halihazırda içinde yaşadığı asenkron, çoklu zaman dilimli iş akışı için tasarlanmıştır.

• Dokümantasyonu ABD, Hindistan, Avrupa ve Latin Amerika'yı kapsayan mühendislik ekipleri için 65'ten fazla dile çevirin.

• Ekibin mevcut wiki, kod deposu ve API dokümanlarının yanında yer alır. Bunların hiçbirinin yerini almaz.

• Değişen adımı yeniden kaydederek güncelleyin. Mimari anlatımı güncelliğini yitirmez.

Trupeer AI'ın mühendislik ekipleri için ürettiği çıktılar

Kıdemli bir mühendis bir ekran kaydı açar. Üretim servisinin yayına alınması, hazırlık (staging) ortamındaki hataların ayıklanması veya ekibin 2024'te yaptığı mesaj kuyruğu tasarım tercihinin açıklanması adımlarını göstererek anlatır. Post prodüksiyonu Trupeer AI halleder. Duraklama kelimeleri kaldırılır. Zoom efektleri, bir sonraki mühendisin bakması gereken terminal komutunu, IDE bölgesini veya paneli vurgular. Taslak bir video ve taslak bir yazılı mühendislik dokümanı, ekran görüntüleri ve numaralı adımlarla birlikte aynı yerde görünür.

Çıktılar MP4 video ve PDF veya Word belgesi olarak gönderilir. Belge, birinin wiki'de okuduğu veya Notion ya da Confluence'a yapıştırdığı şeydir. Videolar ise yardım merkezinde izlenen, bir Linear biletine gömülen veya bir Paylaşılan Sayfa bağlantısı aracılığıyla paylaşılan içeriklerdir. Her ikisi de ikinci bir işleme gerek kalmadan aynı kayıttan elde edilir. Marka kiti, mühendislik ekibine özel giriş ve çıkış slaytları uygular ve özel sözlük; dahili servis adlarını, altyapı bileşen adlarını ve yapay zekanın aksi takdirde doğru yazamayacağı kısaltmaları yönetir.

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

Tüm akış üç adımı kapsar: kıdemli mühendisin kafasında zaten var olanları kaydedin, yapay zekanın her iki formatı da oluşturmasına izin verin ve zaman diliminden bağımsız olarak ekibin geri kalanının bulabileceği bir bağlantı aracılığıyla gönderin.

Adım 1: Açıklamayı kaydedin

Tarayıcıda, mühendislik ekibinin IDE'sinde veya terminal üzerinde bir ekran kaydı başlatın. Kıdemli mühendis, yeni işe alınan biriyle bire bir görüşüyormuş gibi konuyu anlatır. Bir mimari anlatımı veya dağıtım kılavuzu için genellikle beş ila on dakikalık kayıt yeterlidir. Yapay zeka kaydedilenler üzerinde çalıştığı için kıdemli mühendisin taslak yazmasına veya slayt hazırlamasına gerek kalmaz.

Adım 2: Yapay zeka videoyu ve yazılı mühendislik dokümanını oluşturur

Duraklama kelimeleri ve "şu dosyayı bulayım" anları temizlenir. Zoom efektleri, ekranın önemli olan kısımlarını (dosya yolu, terminal çıktısı, PR incelemesindeki değişiklik vb.) vurgular. Taslak bir video ve taslak bir 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ış yazıya dökülmeden önce yakalar.

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

Mühendislik içi belgelerin ekibin kütüphanesinde tutarlı görünmesi için marka kitini uygulayın. Ekibin fiilen çalıştığı dillere çevirin: Mexico City ofisi için İspanyolca, Bangalore ekibi için Hintçe, São Paulo için Portekizce. Wiki'de, ekibin oryantasyon dokümanında yer alan veya doğrudan mühendislerin iş akışını bozmadan bulabilecekleri Slack kanallarına yapıştırılan bir Paylaşılan Sayfa bağlantısı aracılığıyla gönderin.

Bu mühendislik dokümantasyon aracını kimler kullanır?

Bu aracı kullanan kişi genellikle en az iki zaman diliminde çalışanı bulunan, öncelikle uzaktan çalışan veya hibrit bir mühendislik kuruluşundaki kıdemli mühendis, mühendislik yöneticisi veya teknik liderdir. Bu aracı yeni biri işe başladığında ve README yeterli olmadığında, ekip kaydedilmeye değer bariz olmayan mimari bir karar aldığında veya nöbetçi kılavuzunun sadece komutları listelemek yerine gece saat 3'te ne yapılması gerektiğini gerçekten açıklaması gerektiğinde kullanırlar. Bazı ekipler bunu her büyük tasarım kararı için rutin olarak kullanırken, diğerleri sadece kılavuz eksikliği ortaya çıktığında başvurur.

Aynı iş akışı roller arasında da görülür. DevOps ve SRE liderleri, daha geniş mühendislik ekibiyle paylaşılan olay retrospektiflerini ve altyapı kılavuzlarını kaydeder. Mühendislik yöneticileri, yeni işe alınanlar için her hafta DM'lerden aynı soruların sorulmaması için oryantasyon kılavuzları kaydeder. Teknik liderler, gelecekteki mühendislerin bir sistemin neden bu şekilde tasarlandığını bilmeleri için mimari kararları kaydeder. Mühendislik yöneticileri, aksi takdirde kimsenin katılmak istemeyeceği 50 kişilik genel bir toplantı gerektirecek ekipler arası yaygınlaştırma süreçlerini (yeni bir dahili platform, servis geçişi, dağıtım sürecindeki bir değişiklik vb.) kaydeder.

Bu aracın desteklediği mühendislik içerik türleri

En sık karşılaşılan içerik türleri şunlardır: mimari ve tasarım kılavuzları (bu sistem neden böyle görünüyor), dağıtım ve altyapı kılavuzları (üretime nasıl gönderilir, nasıl geri alınır), oryantasyon kılavuzları (kod tabanı turu, yerel geliştirici kurulumu, ilk PR kılavuzu), olay retrospektifleri ve post-mortem analizleri (ne oldu, ne öğrendik, neyi değiştiriyoruz) ve kod inceleme açıklamaları (bariz olmayan bir PR'ın arkasındaki nedenler). Trupeer AI, tüm bunları aynı kayıttan belgeye dönüştürme iş akışıyla yönetir. Çıktı formatı duruma göre uyarlanır: bir acil durum kılavuzu ekran görüntülü numaralı adımları, bir mimari anlatımı yazılı özetle birlikte videoyu, bir oryantasyon turu ise her ikisini de gerektirir.

Daha genel olarak mühendislik dokümantasyonu için Trupeer AI, yalnızca metinden oluşan wiki araçlarının boş bıraktığı açıklama katmanını doldurur. Yazılım mühendisliği dokümantasyonu genellikle üç katmana ayrılır: kodla oluşturulan referans dokümanları (Sphinx, javadoc, OpenAPI), ekip wiki içerikleri (Confluence, Notion, Slab) ve insan tarafından kaydedilen görsel-işitsel kılavuzlar. Çoğu mühendislik ekibinde ilk katman vardır çünkü otomatiktir ve ikinci katman da birilerine bunu yazması için ödeme yapıldığı için mevcuttur. Üçüncü katman (yazılım mühendisliğinde sistem dokümantasyonu, mühendislik projesi dokümantasyonu, yazılım mühendisliğinde dahili dokümantasyon) her zaman geride kalan katmandır. Trupeer AI, bu üçüncü katmanı üretmeyi kıdemli bir mühendisin bir cuma öğleden sonra toplantılar arasında yapabileceği kadar hızlı hale getirir.

Trupeer; wiki'lerin, kod belgeleme araçlarının ve API dokümantasyon oluşturucularının yanında nereye konumlanıyor?

Trupeer AI ekibin wiki'sinin yerini almaz. Confluence, Notion, Slab, GitBook ve dahili ekip wiki'leri işlerini yapmaya devam eder. Trupeer AI, ekibin zaten yazdığı makalelerin yanı sıra, bu wiki'lere Paylaşılan Sayfa olarak gömülen kayıtlı açıklama içeriklerini üretir.

Trupeer AI, API dokümantasyon oluşturucularının da yerini almaz. Swagger, Stoplight, Redoc, Postman ve otomatik olarak oluşturulan her türlü OpenAPI referansı, uç nokta seviyesindeki referans belgelerini yönetmeye devam eder. Trupeer AI farklı bir katmanda yer alır: API'nin nasıl tasarlandığına, onunla fiilen nasıl entegrasyon sağlanacağına ve referans belgelerinde görünmeyen püf noktalarının neler olduğuna dair insan anlatımıyla rehberlik sunar. Bir mühendislik ekibinin dokümantasyon kütüphanesi tipik olarak hem otomatik olarak oluşturulan referansa hem de insan tarafından kaydedilen kılavuza ihtiyaç duyar. Trupeer AI yalnızca ikincisini yönetir; ilki olduğu yerde kalır. Aynı mantık, Trupeer AI'ın rakip olmak yerine tamamlayıcı olduğu Doxygen, javadoc ve satır içi yorum sistemleri gibi kod düzeyindeki araçlar için de geçerlidir. Mühendislik dokümantasyon yönetimi ve daha geniş anlamda teknik dokümantasyon için bu, ekibin halihazırda sahip olduğu hiçbir şeyi bozmadan bir açıklama katmanı eklemesi anlamına gelir.

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

Mühendislik dokümantasyonu, altta yatan sistemler haftalık olarak değiştiği için mühendislik dışı ekiplerin beklediğinden daha hızlı eskir. Dağıtım hattındaki bir değişiklik geçen çeyreğin kılavuzunu bozar, bir mimari yeniden yapılandırması tasarım dokümanını yanıltıcı hale getirir, yeniden adlandırılan bir servis oryantasyon kılavuzunu kafa karıştırıcı hale getirir. Çoğu ekip bunu, belgelerin güncelliğini yitirmesine sessizce göz yumarak ve birisi artık eskiyen belgeye her denk geldiğinde soruları Slack üzerinden yanıtlayarak idare eder. Trupeer AI, güncellemeleri yalnızca değişen bölümü yeniden kaydederek yönetir. Yapay zeka yalnızca o kısmı yeniden işler, hem video hem de yazılı mühendislik dokümanı olduğu yerde güncellenir ve wiki'ye bakan bir sonraki mühendis güncel sürümü görür.

Küresel olarak dağıtılmış mühendislik ekipleri için çeviri, günlük toplantılarda kimsenin bahsetmediği pürüzleri azaltır. Aynı mimari anlatımı, aynı kaynak kayıttan, aynı hafta içinde Bangalore ekibine Hintçe, Berlin ekibine Almanca ve São Paulo ekibine Portekizce olarak ulaşır. Çeviri, marka kiti, sözlük ve ekran metinleri korunarak hem video seslendirmesine hem de yazılı mühendislik dokümanına uygulanır. Bu mühendislik ekibi dokümantasyon iş akışını Trupeer AI SOP oluşturucu ile eşleştirmek, hem mühendisliğe yönelik kılavuzları hem de mühendislik ekiplerinin kuruluşun diğer bölümlerine devrettiği işlevler arası standart çalışma prosedürlerini kapsar.