원격 엔지니어링 팀을 위한 문서화 도구

Trupeer AI는 옆 사람에게 직접 물어볼 수 없는 원격 엔지니어링 팀을 위한 제품 설명 비디오 및 문서 자동화 툴입니다. 시니어 엔지니어가 한 번 설명을 녹화하면(배포 파이프라인이 실제로 작동하는 방식, 이 서비스가 재시도를 그렇게 처리하는 이유, 코드베이스의 까다로운 부분이 무엇이고 왜 까다로운지 등), Trupeer AI는 한 번의 작업으로 비디오와 작성된 엔지니어링 문서를 모두 생성합니다. 다른 시간대와 다른 사무실에서 작업하는 다른 엔지니어들은 비동기식으로 시청하고 읽습니다. 분산 엔지니어링 팀은 README 파일이 없어서라기보다는 README 뒤에 숨겨진 설명이 없어서 어려움을 겪고 있는데, 이 설명은 시니어 엔지니어가 작성하는 데 반나절이 걸리고 누구도 그럴 만한 여유가 없는 부분입니다.

• 시니어 엔지니어가 가이드를 녹화하면, 비디오와 작성된 엔지니어링 문서가 함께 제공됩니다.

• 분산 엔지니어링 팀이 이미 살고 있는 비동기식, 다중 시간대 워크플로우에 맞게 구축되었습니다.

• 미국, 인도, 유럽 및 남미에 이르는 엔지니어링 팀을 위해 문서를 65개 이상의 언어로 번역하세요.

• 팀의 기존 위키, 코드 저장소 및 API 문서와 함께 배치됩니다. 이들 중 어느 것도 대체하지 않습니다.

• 변경된 단계만 다시 녹화하여 업데이트하세요. 아키텍처 설명서가 최신 상태에서 벗어나지 않습니다.

Trupeer AI가 엔지니어링 팀을 위해 제공하는 것

시니어 엔지니어가 화면 녹화를 시작합니다. 프로덕션 서비스 배포, 스테이징 환경 디버깅 또는 팀이 2024년에 선택한 메시지 큐 디자인 설계에 대해 짚어가며 설명합니다. Trupeer AI가 후반 작업을 처리합니다. 불필요한 추임새는 제거됩니다. 줌 효과는 터미널 명령, IDE 영역 또는 다음 엔지니어가 봐야 할 대시보드를 강조 표시합니다. 초안 비디오와 초안 엔지니어링 문서가 스크린샷 및 번호가 매겨진 단계와 함께 한곳에 나타납니다.

출력물은 MP4 비디오와 PDF 또는 Word 문서로 제공됩니다. 문서는 위키에서 읽거나 Notion 또는 Confluence에 붙여넣는 자료입니다. 비디오는 헬프 센터에서 시청하거나, Linear 티켓에 임베드하거나, 공유 페이지 링크를 통해 공유하는 자료입니다. 두 가지 모두 두 번째 작업 없이 동일한 녹화본에서 생성됩니다. 브랜드 키트는 엔지니어링 팀 전용 인트로 및 아웃트로 슬라이드를 적용하고, 맞춤형 사용 용어집은 AI가 제대로 철자를 쓰지 못할 수 있는 내부 서비스 이름, 인프라 구성 요소 이름 및 약어를 처리합니다.

엔지니어링 문서화 툴 작동 방식 3단계

전체 흐름은 시니어 엔지니어가 이미 머릿속으로 생각하고 있는 내용을 녹화하고, AI가 두 가지 형식을 모두 생성하도록 한 다음, 시간대에 관계없이 나머지 팀원들이 찾을 수 있는 링크를 통해 배포하는 세 단계로 이루어집니다.

1단계: 설명 녹화

브라우저, 엔지니어링 팀의 IDE 또는 터미널을 통해 화면 녹화를 시작합니다. 시니어 엔지니어는 신입 사원과의 1:1 대화에서 설명하는 것과 같은 방식으로 작업 내용을 이야기합니다. 아키텍처 설명이나 배포 프로세스 가이드의 경우 대개 5~10분의 녹화로 충분합니다. AI가 녹화된 내용을 기반으로 작업하므로 시니어 엔지니어가 초안을 작성하거나 슬라이드를 준비할 필요가 없습니다.

2단계: AI의 비디오 및 엔지니어링 문서 생성

불필요한 추임새 및 "그 파일 좀 찾을게요"와 같은 지체되는 순간들이 제거됩니다. 줌 효과는 화면에서 중요한 부분(파일 경로, 터미널 출력, PR 리뷰의 차이점)을 강조합니다. 초안 비디오와 초안 문서가 에디터에 함께 표시됩니다. 맞춤형 사용 용어집은 내부 서비스명과 구성 요소 약어가 잘못 전사되기 전에 올바르게 잡아냅니다.

3단계: 브랜드 적용, 번역, 공유

엔지니어링 내부 문서가 팀 라이브러리 전체에서 일관되게 보이도록 브랜드 키트를 적용합니다. 멕시코시티 사무소의 경우 스페인어, 벵갈루루 팀의 경우 힌디어, 상파울루는 포르투갈어 등 팀이 실제로 사용하는 언어로 번역합니다. 위키, 팀의 온보딩 문서에 상주하거나 Slack 스레드에 직접 붙여넣을 수 있는 공유 페이지 링크를 통해 공유하여 엔지니어들이 흐름을 깨지 않고 찾을 수 있도록 합니다.

누가 이 엔지니어링 문서화 툴을 사용하나요?

이 툴을 사용하는 사람은 대개 직원이 최소 두 개 이상의 시간대에 분산되어 있는 원격 우선 또는 하이브리드 엔지니어링 조직의 스태프 엔지니어, 엔지니어링 매니저 또는 테크 리드입니다. 이들은 신입 사원이 합류하고 README만으로는 충분하지 않을 때, 팀이 이유를 기록해 둘 가치가 있는 명확하지 않은 아키텍처 결정을 내릴 때, 또는 온콜 런북에 단순히 명령어를 나열하는 대신 새벽 3시에 실제로 무엇을 해야 하는지 설명해야 할 때 이 툴을 사용합니다. 어떤 팀은 모든 주요 설계 결정에 이 툴을 정기적으로 사용하고, 어떤 팀은 설명이 필요한 공백이 생길 때만 사용합니다.

동일한 워크플로우가 여러 역할에서 나타납니다. DevOps 및 SRE 리드는 장애 회고 및 인프라 가이드를 녹화하여 더 넓은 엔지니어링 조직에 공유합니다. 엔지니어링 매니저는 신입 사원을 위한 온보딩 가이드를 녹화하여 매주 DM으로 동일한 질문을 받지 않도록 합니다. 테크 리드는 시스템이 왜 그렇게 설계되었는지 미래의 엔지니어들이 알 수 있도록 아키텍처 결정을 녹화합니다. 엔지니어링 총괄은 아무도 참석하고 싶어 하지 않는 50인 규모의 전체 회의가 필요한 교차 팀 롤아웃(새로운 내부 플랫폼, 서비스 마이그레이션, 배포 프로세스 변경)을 녹화합니다.

이 툴이 처리하는 엔지니어링 콘텐츠 유형

가장 자주 등장하는 콘텐츠 유형은 아키텍처 및 디자인 가이드(이 시스템이 왜 이렇게 생겼는지), 배포 및 인프라 런북(프로덕션 배포 방법, 롤백 방법), 온보딩 가이드(코드베이스 투어, 로컬 개발 환경 설정, 첫 번째 PR 프로세스), 장애 회고 및 사후 분석(무슨 일이 일어났는지, 무엇을 배웠는지, 무엇을 변경하는지), 코드 리뷰 설명(명확하지 않은 PR 뒤의 이유) 등입니다. Trupeer AI는 기록에서 문서화에 이르는 동일한 흐름으로 이 모든 과정을 처리합니다. 형식은 조정 가능합니다. 런북은 스크린샷과 함께 번호가 매겨진 단계를 원하고, 아키텍처 설명서는 문서 요약과 함께 비디오를 원하며, 온보딩 투어는 둘 다 원합니다.

엔지니어링 문서 전반에서, Trupeer AI는 텍스트 위주의 위키 툴이 채우지 못하는 설명 영역을 보완합니다. 소프트웨어 엔지니어링 문서는 일반적으로 코드로 생성된 참조 문서(Sphinx, javadoc, OpenAPI), 팀 위키 콘텐츠(Confluence, Notion, Slab), 사람이 녹화한 설명 가이드의 세 가지 계층으로 나뉩니다. 대부분의 엔지니어링 팀은 첫 번째 레이어가 자동으로 생성되고, 두 번째 레이어는 누군가 시간을 들여 작성했기 때문에 가지고 있습니다. 세 번째 레이어(소프트웨어 엔지니어링의 시스템 문서, 엔지니어링 프로젝트 문서, 소프트웨어 엔지니어링의 내부 문서)는 항상 지연되는 부분입니다. Trupeer AI는 시니어 엔지니어가 회의 사이 금요일 오후에 할 수 있을 만큼 이 세 번째 레이어의 제작 속도를 빠르게 만들어 줍니다.

위키, 코드 문서 툴, API 문서 생성기 옆에서 Trupeer의 위치

Trupeer AI는 팀의 위키를 대체하지 않습니다. Confluence, Notion, Slab, GitBook 및 내부 팀 위키는 계속 제 역할을 수행합니다. Trupeer AI는 팀이 이미 작성하는 텍스트 문서와 함께 공유 페이지로 해당 위키에 임베드되는 녹화된 설명 콘텐츠를 생성합니다.

또한, Trupeer AI는 API 문서 생성기를 대체하지 않습니다. Swagger, Stoplight, Redoc, Postman 및 자동 생성된 OpenAPI 레퍼런스는 계속해서 엔드포인트 수준의 레퍼런스 문서를 처리합니다. Trupeer AI는 다른 레이어에 위치합니다. 즉, API가 어떻게 설계되었는지, 실제로 어떻게 연동하는지, 그리고 레퍼런스 문서가 명시하지 않는 까다로운 점이 무엇인지에 대해 사람이 직접 가이드하는 레이어입니다. 엔지니어링 팀의 문서 라이브러리에는 일반적으로 자동 생성된 레퍼런스와 사람이 녹화한 설명서가 둘 다 필요합니다. Trupeer AI는 두 번째만 처리하며, 첫 번째는 기존 위치에 유지됩니다. Doxygen, javadoc, 인라인 주석 시스템과 같은 코드 수준의 툴링에도 동일한 논리가 적용되며, Trupeer AI는 이를 경쟁하기보다 보완합니다. 엔지니어링 문서 관리 및 기술 문서 전반에 있어서, 이는 팀이 이미 가지고 있는 어떤 것도 제거하지 않고 설명 레이어를 추가함을 의미합니다.

글로벌 분산 엔지니어링 팀을 위한 업데이트 및 번역

엔지니어링 문서는 기본 시스템이 매주 변경되기 때문에 비엔지니어링 팀이 예상하는 것보다 더 빨리 쓸모가 없어집니다. 배포 파이프라인의 변경은 지난 분기의 런북을 깨뜨리고, 아키텍처 리팩토링은 디자인 문서를 오도하게 만들며, 이름이 변경된 서비스는 온보딩 가이드를 혼란스럽게 만듭니다. 대부분의 팀은 문서를 조용히 방치하고 누군가 쓸모없는 문서에 도달할 때마다 Slack에서 질문에 답변하는 방식으로 이를 처리합니다. Trupeer AI는 변경된 세그만트만 다시 녹화하여 업데이트를 처리합니다. AI는 해당 부분만 재처리하고, 비디오와 문서가 그 자리에서 모두 업데이트되므로, 다음에 위키를 보는 엔지니어는 현재 버전을 보게 됩니다.

글로벌 분산 엔지니어링 팀의 경우, 번역은 스탠드업 미팅에서 아무도 언급하지 않는 마찰을 줄여줍니다. 동일한 소스 녹화본에서 시작하여 동일한 주에 벵갈루루 팀에는 힌디어로, 베를린 팀에는 독일어로, 상파울루 팀에는 포르투갈어로 아키텍처 설명서가 전달됩니다. 번역은 브랜드 키트, 용어집 및 화면 상의 텍스트가 그대로 적용된 상태에서 비디오 음성 더빙과 작성된 엔지니어링 문서 모두에 적용됩니다. 이 엔지니어링 팀 문서화 워크플로우를 Trupeer AI SOP 빌더와 결합하면 엔지니어링 대상의 가이드와 엔지니어링 팀이 조직의 다른 부서에 전달하는 교차 기능 표준 운영 절차(SOP)를 모두 처리할 수 있습니다.