Alat Dokumentasi untuk Tim Rekayasa Jarak Jauh

Trupeer AI adalah alat dokumentasi panduan untuk tim teknik jarak jauh yang tidak bisa membungkuk dan bertanya langsung kepada orang di sebelah mereka. Seorang insinyur senior merekam penjelasan sekali saja (bagaimana pipa penerapan sebenarnya berfungsi, mengapa layanan ini menangani upaya ulang dengan cara seperti ini, apa yang dilakukan bagian kode basis yang rumit dan mengapa itu rumit), dan Trupeer AI menghasilkan video dan dokumen teknik tertulis dalam satu pengerjaan yang sama. Insinyur lain, yang bekerja di zona waktu berbeda dan kantor berbeda, menonton dan membacanya secara asinkron. Tim teknik terdistribusi tidak terlalu menderita karena kehilangan README, melainkan karena kehilangan penjelasan di balik README tersebut, yang merupakan bagian yang membutuhkan waktu setengah hari bagi insinyur senior untuk menulisnya dan tidak pernah ada yang memiliki kapasitas untuk itu.

• Insinyur senior merekam panduan tersebut. Video dan dokumen teknik tertulis tiba bersamaan.

• Dibuat untuk alur kerja asinkron multi-zona waktu yang sudah dijalani oleh tim teknik terdistribusi.

• Terjemahkan dokumentasi ke dalam 65+ bahasa untuk tim teknik yang tersebar di AS, India, Eropa, dan LATAM.

• Dapat bersanding dengan wiki tim, repositori kode, dan dokumen API yang sudah ada. Tidak menggantikan satu pun dari mereka.

• Perbarui dengan merekam ulang langkah yang berubah. Penjelasan arsitektur tidak akan menjadi usang.

Apa yang dihasilkan Trupeer AI untuk tim teknik

Seorang insinyur senior membuka rekaman layar. Mereka memandu proses penerapan layanan produksi, menelusuri kesalahan lingkungan pementasan, atau menjelaskan pilihan desain antrean pesan yang dibuat tim pada tahun 2024. Trupeer AI menangani pascaproduksi. Kata-kata pengisi dihilangkan. Efek zoom menyoroti perintah terminal, wilayah IDE, atau dasbor yang perlu dilihat oleh insinyur berikutnya. Draf video dan draf dokumen teknik tertulis muncul di tempat yang sama, lengkap dengan tangkapan layar dan langkah-langkah bernomor secara langsung.

Output dikirim sebagai video MP4 dan dokumen PDF atau Word. Dokumen tersebut adalah apa yang dibaca seseorang di wiki atau ditempelkan ke Notion atau Confluence. Video adalah apa yang ditonton seseorang di pusat bantuan, disematkan dalam tiket Linear, atau dibagikan melalui tautan Halaman Bersama. Keduanya berasal dari rekaman yang sama tanpa perlu proses kedua. Kit merek menerapkan slide pembuka dan penutup khusus tim teknik, dan glosarium khusus menangani nama layanan internal, nama komponen infrastruktur, dan akronim yang jika tidak, tidak akan dieja dengan benar oleh AI.

Cara kerja alat dokumentasi teknik dalam tiga langkah

Tiga langkah mencakup seluruh alur: rekam apa yang sudah ada di kepala insinyur senior, biarkan AI menghasilkan kedua format tersebut, dan kirimkan melalui tautan yang dapat ditemukan oleh anggota tim lainnya terlepas dari zona waktu mereka.

Langkah 1: Rekam penjelasan

Mulai perekaman layar di browser, di IDE tim teknik, atau di terminal. Insinyur senior menjelaskan pekerjaan tersebut dengan cara yang sama seperti yang mereka lakukan dalam sesi 1:1 dengan karyawan baru. Perekaman selama lima hingga sepuluh menit biasanya sudah cukup untuk penjelasan arsitektur atau panduan penerapan. AI bekerja berdasarkan apa yang direkam, sehingga insinyur senior tidak perlu menulis draf atau menyiapkan slide.

Langkah 2: AI menghasilkan video dan dokumen teknik tertulis

Kata-kata pengisi dan momen "izinkan saya mencari file itu" akan dihapus. Efek zoom menyoroti bagian layar yang penting (jalur file, output terminal, perbedaan dalam ulasan PR). Draf video dan draf dokumen teknik tertulis muncul bersamaan di editor. Glosarium khusus menangkap nama layanan internal dan akronim komponen sebelum ditranskripsikan secara salah.

Langkah 3: Beri merek, terjemahkan, bagikan

Terapkan kit merek agar dokumen internal teknik terlihat konsisten di seluruh pustaka tim. Terjemahkan ke dalam bahasa yang sebenarnya digunakan tim: bahasa Spanyol untuk kantor Mexico City, bahasa Hindi untuk tim Bangalore, bahasa Portugis untuk São Paulo. Kirimkan melalui tautan Halaman Bersama yang ada di wiki, di dokumen orientasi tim, atau ditempelkan langsung ke utas Slack tempat para insinyur dapat menemukannya tanpa mengganggu alur kerja.

Siapa yang membuka alat dokumentasi teknik ini

Orang yang membuka alat ini biasanya adalah staf insinyur, manajer teknik, atau pimpinan teknologi di organisasi teknik hibrida atau sepenuhnya jarak jauh dengan anggota tim di setidaknya dua zona waktu. Mereka membukanya saat ada karyawan baru bergabung dan README saja tidak cukup, saat tim membuat keputusan arsitektur yang tidak langsung terlihat jelas sehingga perlu direkam alasannya, atau saat panduan siaga perlu benar-benar menjelaskan apa yang harus dilakukan pada jam 3 pagi alih-alih hanya mencantumkan perintah. Beberapa tim menggunakannya secara rutin untuk setiap keputusan desain utama; yang lain hanya menggunakannya saat diperlukan penjelasan yang mendalam.

Alur kerja yang sama terjadi di berbagai peran. Pimpinan DevOps dan SRE merekam retrospektif insiden dan panduan infrastruktur yang dibagikan ke organisasi teknik yang lebih luas. Manajer teknik merekam panduan orientasi untuk karyawan baru agar pertanyaan yang sama tidak ditanyakan di DM setiap minggu. Pimpinan teknologi merekam keputusan arsitektur agar insinyur di masa mendatang tahu mengapa sistem dirancang seperti itu. Kepala teknik merekam peluncuran lintas tim (platform internal baru, migrasi layanan, perubahan pada proses penerapan) yang jika tidak, akan memerlukan pertemuan besar beranggotakan 50 orang yang tidak ingin dihadiri oleh siapa pun.

Jenis konten teknik yang ditangani alat ini

Jenis konten yang paling sering muncul: panduan arsitektur dan desain (mengapa sistem ini terlihat seperti ini), panduan penerapan dan infrastruktur (cara mengirim ke produksi, cara mengembalikan), panduan orientasi (tur basis kode, pengaturan pengembangan lokal, panduan PR pertama), retrospektif dan evaluasi insiden (apa yang terjadi, apa yang kami pelajari, apa yang kami ubah), dan penjelasan tinjauan kode (alasan di balik PR yang tidak biasa). Trupeer AI menangani semuanya dengan alur kerja perekaman-ke-dokumen yang sama. Formatnya menyesuaikan: panduan penerapan membutuhkan langkah-langkah bernomor dengan tangkapan layar, penjelasan arsitektur membutuhkan video dengan ringkasan tertulis, tur orientasi membutuhkan keduanya.

Untuk dokumentasi teknik secara lebih luas, Trupeer AI mengisi lapisan penjelasan yang dikosongkan oleh alat wiki khusus teks. Dokumentasi rekayasa perangkat lunak biasanya terbagi dalam tiga lapisan: dokumen referensi yang dihasilkan kode (Sphinx, javadoc, OpenAPI), konten wiki tim (Confluence, Notion, Slab), dan panduan yang direkam manusia. Sebagian besar tim teknik memiliki lapisan pertama karena otomatis dan lapisan kedua karena ada yang dibayar untuk menulisnya. Lapisan ketiga (dokumentasi sistem dalam rekayasa perangkat lunak, dokumentasi proyek teknik, dokumentasi internal dalam rekayasa perangkat lunak) adalah lapisan yang selalu tertinggal. Trupeer AI membuat pembuatan lapisan ketiga itu cukup cepat sehingga seorang insinyur senior dapat melakukannya pada Jumat sore di sela-sela rapat.

Di mana posisi Trupeer di samping wiki, alat kode-dok, dan pembuat dokumentasi API

Trupeer AI tidak menggantikan wiki tim. Confluence, Notion, Slab, GitBook, dan wiki tim internal tetap melakukan tugasnya masing-masing. Trupeer AI menghasilkan konten penjelasan terekam yang disematkan ke dalam wiki tersebut sebagai Halaman Bersama, di samping artikel tertulis yang sudah ditulis tim.

Trupeer AI juga tidak menggantikan generator dokumentasi API. Swagger, Stoplight, Redoc, Postman, dan referensi OpenAPI apa pun yang dibuat otomatis tetap menangani dokumen referensi tingkat titik akhir. Trupeer AI berada di lapisan yang berbeda: panduan manusia tentang bagaimana API dirancang, bagaimana cara mengintegrasikannya secara nyata, dan apa saja kendala yang tidak muncul di dokumen referensi. Pustaka dokumentasi tim teknik biasanya membutuhkan keduanya, referensi yang dibuat otomatis dan penjelasan yang direkam manusia. Trupeer AI hanya menangani yang kedua; yang pertama tetap di tempat asalnya. Logika yang sama berlaku untuk alat tingkat kode seperti Doxygen, javadoc, dan sistem komentar sebaris, yang dilengkapi oleh Trupeer AI daripada disaingi. Untuk manajemen dokumentasi teknik dan dokumentasi teknis secara lebih luas, ini berarti tim menambahkan lapisan penjelasan tanpa harus menghapus apa pun yang sudah mereka miliki.

Pembaruan dan penerjemahan untuk tim teknik yang terdistribusi secara global

Dokumentasi teknik usang lebih cepat daripada yang diperkirakan oleh tim non-teknik karena sistem yang mendasarinya berubah setiap minggu. Perubahan pipa penerapan merusak panduan kuartal lalu, pemfaktoran ulang arsitektur membuat dokumen desain menjadi menyesatkan, layanan yang diganti namanya membuat panduan orientasi menjadi membingungkan. Sebagian besar tim menangani hal ini dengan membiarkan dokumen usang begitu saja dan menjawab pertanyaan di Slack setiap kali seseorang menemukan dokumen yang kedaluwarsa tersebut. Trupeer AI menangani pembaruan dengan merekam ulang segmen yang berubah saja. AI hanya memproses ulang bagian tersebut, video dan dokumen teknik tertulis diperbarui di tempat, dan insinyur berikutnya yang melihat wiki akan melihat versi saat ini.

Untuk tim teknik yang terdistribusi secara global, penerjemahan mengurangi hambatan yang tidak pernah disebutkan dalam rapat harian. Penjelasan arsitektur yang sama menjangkau tim Bangalore dalam bahasa Hindi, tim Berlin dalam bahasa Jerman, dan tim São Paulo dalam bahasa Portugis, dari rekaman sumber yang sama, di minggu yang sama. Terjemahan berlaku untuk sulih suara video dan dokumen teknik tertulis, dengan kit merek, glosarium, dan teks di layar yang disesuaikan. Memasangkan alur kerja dokumentasi tim teknik ini dengan pembuat SOP Trupeer AI mencakup panduan yang menghadap ke tim teknik dan prosedur operasi standar lintas fungsi yang diserahkan tim teknik ke bagian lain dalam organisasi.