Dokumentationsværktøj til distribuerede ingeniørteams

Trupeer AI er værktøjet til gennemgangsdokumentation for distribuerede ingeniørteams, der ikke bare kan læne sig over og spørge personen ved siden af. En senioringeniør optager forklaringen én gang (hvordan deploy-pipelinen faktisk fungerer, hvorfor denne tjeneste håndterer genafprøvninger på den måde, den gør, hvad den komplekse del af kodebasen gør, og hvorfor den er kompleks), og Trupeer AI genererer både en video og et skriftligt ingeniørdokument i samme arbejdsgang. Andre ingeniører, der arbejder i forskellige tidszoner og på forskellige kontorer, ser og læser asynkront. Distribuerede ingeniørteams lider ikke så meget under manglende README'er som af at mangle forklaringen bag README'en, hvilket er den del, det tager en senioringeniør en eftermiddag at skrive, og som ingen nogensinde har tid til.

• Senioringeniøren optager gennemgangen. Video og skriftligt ingeniørdokument leveres sammen.

• Bygget til det asynkrone arbejdsflow på tværs af flere tidszoner, som distribuerede ingeniørteams allerede lever i.

• Oversæt dokumentation til 65+ sprog til ingeniørteams i USA, Indien, Europa og LATAM.

• Ligger side om side med teamets eksisterende wiki, kodearkiv og API-dokumenter. Erstatter ingen af dem.

• Opdater ved at genoptage det ændrede trin. Forklaringen af arkitekturen bliver ikke forældet.

Hvad Trupeer AI producerer til ingeniørteams

En senioringeniør starter en skærmoptagelse. De gennemgår udrulningen af produktionsservicen, fejlfinding i staging-miljøet eller forklarer det valg af beskedkø-design, som teamet traf i 2024. Trupeer AI håndterer efterbehandlingen. Fyldord fjernes. Zoomeffekter fremhæver terminalkommandoen, IDE-området eller det dashboard, den næste ingeniør skal kigge på. Et udkast til en video og et udkast til et skriftligt ingeniørdokument dukker op på samme sted med skærmbilleder og nummererede trin inkluderet undervejs.

Output leveres som MP4-video og PDF- eller Word-dokument. Dokumentet er det, man læser i en wiki eller indsætter i Notion eller Confluence. Videoer er det, man ser i hjælpecentret, indlejret i en Linear-ticket eller delt via et Shared Page-link. Begge dele kommer fra den samme optagelse uden behov for en ekstra redigering. Brandkittet tilføjer intro- og outro-slides, der er specifikke for ingeniørteamet, og den brugerdefinerede ordliste håndterer interne servicenavne, infrastrukturkomponentnavne og akronymer, som AI'en ellers ikke ville stave rigtigt.

Sådan fungerer værktøjet til ingeniørdokumentation i tre trin

Tre trin dækker hele workflowet: Optag det, som senioringeniøren allerede har i hovedet, lad AI'en generere begge formater, og distribuer via et link, som resten af teamet kan finde uanset tidszone.

Trin 1: Optag forklaringen

Start en skærmoptagelse i browseren, i ingeniørteamets IDE eller direkte i terminalen. Senioringeniøren forklarer arbejdet på samme måde, som de ville gøre i en 1:1 med en nyansat. Fem til ti minutters optagelse er normalt nok til en arkitekturforklaring eller en gennemgang af en udrulning. AI'en arbejder ud fra det, der er optaget, så senioringeniøren behøver ikke at skrive et udkast eller forberede slides.

Trin 2: AI genererer videoen og det skriftlige ingeniørdokument

Fyldord og "lad mig lige finde den fil"-øjeblikke fjernes. Zoomeffekter fremhæver de dele af skærmen, der betyder noget (filstien, terminaloutputtet, forskellen i PR-gennemgangen). Et udkast til en video og et udkast til et skriftligt ingeniørdokument dukker op i editoren sammen. Den brugerdefinerede ordliste fanger interne servicenavne og komponentakronymer, inden de bliver transkriberet forkert.

Trin 3: Brand, oversæt, del

Anvend brand kit, så ingeniørinterne dokumenter ser ensartede ud på tværs af teamets bibliotek. Oversæt til de sprog, teamet rent faktisk arbejder på: spansk til kontoret i Mexico City, hindi til Bangalore-teamet, portugisisk til São Paulo. Del via et Shared Page-link, der findes i wikien, i teamets onboarding-dokument eller indsat direkte i Slack-tråde, hvor ingeniører kan finde det uden at afbryde deres workflow.

Hvem der bruger dette værktøj til ingeniørdokumentation

Den person, der åbner dette værktøj, er normalt en staff engineer, en engineering manager eller en tech lead i en remote-first eller hybrid ingeniørorganisation med folk i mindst to forskellige tidszoner. De åbner det, når en ny medarbejder starter, og README'en ikke er nok, når teamet træffer en ikke-indlysende arkitektonisk beslutning, hvor det er værd at dokumentere argumenterne, eller når on-call-drejebogen faktisk skal forklare, hvad man skal gøre kl. 03.00 om natten i stedet for blot at liste kommandoer. Nogle teams bruger det rutinemæssigt til enhver større designbeslutning; andre tyr kun til det, når det bliver tydeligt, at der mangler en forklaring.

Det samme workflow gør sig gældende på tværs af roller. DevOps- og SRE-ledere optager hændelsesevalueringer og gennemgange af infrastruktur, som deles med den bredere ingeniørorganisation. Engineering managers optager onboarding-gennemgange for nyansatte, så de samme spørgsmål ikke bliver stillet i direkte beskeder hver uge. Tech leads optager arkitekturbeslutninger, så fremtidige ingeniører ved, hvorfor et system ser ud, som det gør. Ingeniørchefer optager udrulninger på tværs af teams (en ny intern platform, en servicemigrering, en ændring i udrulningsprocessen), som ellers ville kræve et stormøde for 50 personer, som ingen har lyst til at deltage i.

Typer af ingeniørindhold, dette værktøj håndterer

De typer af indhold, der oftest opstår, er: gennembange af arkitektur og design (hvorfor dette system ser ud som det gør), køreplaner for udrulning og infrastruktur (hvordan man udruller til produktion, hvordan man ruller tilbage), onboarding-gennemgange (rundvisning i kodebasen, lokal udviklingsopsætning, den første PR-gennemgang), hændelsesevalueringer og post-mortems (hvad der skete, hvad vi lærte, hvad vi ændrer) og forklaringer til kodereview (hvorfor bag en ikke-indlysende PR). Trupeer AI håndterer dem alle med det samme workflow fra optagelse til dokument. Formatet tilpasser sig: En køreplan kræver nummererede trin med skærmbilleder, en arkitekturforklaring har brug for videoen med den skriftlige opsummering, og en onboarding-rundvisning kræver begge dele.

For ingeniørdokumentation mere generelt udfylder Trupeer AI det forklaringslag, som tekstbaserede wiki-værktøjer lader stå tomt. Softwareingeniørdokumentation falder typisk i tre lag: kodegenererede referencedokumenter (Sphinx, javadoc, OpenAPI), team-wiki-indhold (Confluence, Notion, Slab) og menneskeligt optagede gennemgange. De fleste ingeniørteams har det første lag, fordi det er automatisk, og det andet, fordi nogen fik løn for at skrive det. Det tredje lag (systemdokumentation inden for softwareingeniørvidenskab, ingeniørprojektdokumentation, intern dokumentation inden for softwareingeniørvidenskab) er det, der altid halter bagefter. Trupeer AI gør det hurtigt nok at producere dette tredje lag til, at en senioringeniør kan gøre det en fredag eftermiddag mellem møder.

Hvor Trupeer passer ind ved siden af wikier, kodeproducerende værktøjer og API-dokumentationsgeneratorer

Trupeer AI erstatter ikke teamets wiki. Confluence, Notion, Slab, GitBook og den interne team-wiki fortsætter med at gøre det, de gør. Trupeer AI producerer det optagede forklaringsindhold, der bliver indlejret i disse wikier som en Shared Page, sammen med de skriftlige artikler, som teamet allerede skriver.

Trupeer AI erstatter heller ikke API-dokumentationsgeneratorer. Swagger, Stoplight, Redoc, Postman og enhver autogenereret OpenAPI-reference fortsætter med at håndtere referencedokumenter på endpoint-niveau. Trupeer AI befinder sig på et andet niveau: den menneskelige gennemgang af, hvordan API'et blev designet, hvordan man faktisk integrerer mod det, og hvad faldgruberne er, som referencedokumenterne ikke viser. Et ingeniørteams dokumentationsbibliotek har typisk brug for begge dele: den autogenererede reference og den menneskeligt optagede forklaring. Trupeer AI håndterer kun sidstnævnte; det førstnævnte bliver, hvor det er. Den samme logik gælder for værktøjer på kodeniveau som Doxygen, javadoc og inline-kommentarsystemer, som Trupeer AI supplerer snarere end konkurrerer med. For håndtering af ingeniørdokumentation og teknisk dokumentation mere generelt betyder det, at teamet tilføjer et forklaringslag uden at fjerne noget, de allerede har.

Opdateringer og oversættelse for globalt distribuerede ingeniørteams

Ingeniørdokumentation forældes hurtigere, end ikke-tekniske teams forventer, fordi de underliggende systemer ændrer sig ugentligt. En ændring i deploy-pipelinen ødelægger sidste kvartals køreplan, en arkitekturrefaktorering gør designdokumentet misvisende, en omdøbt tjeneste gør onboarding-gennemgangen forvirrende. De fleste teams håndterer dette ved i stilhed at lade dokumenterne forfalde og besvare spørgsmålene på Slack, hver gang nogen støder på det forældede dokument. Trupeer AI håndterer opdateringer ved kun at genoptage det ændrede segment. AI'en genbehandler kun den del, så både video og det skriftlige ingeniørdokument opdateres på stedet, og den næste ingeniør, der kigger i wikien, ser den aktuelle version.

For globalt distribuerede ingeniørteams reducerer oversættelse de gnidninger, som ingen nævner i standup-møderne. Den samme arkitekturforklaring når Bangalore-teamet på hindi, Berlin-teamet på tysk og São Paulo-teamet på portugisisk, ud fra den samme kildeoptagelse, i samme uge. Oversættelsen gælder for både video-voiceoveren og det skriftlige ingeniørdokument, hvor brand kit, ordliste og tekst på skærmen følger med. Ved at parre dette workflow til ingeniørdokumentation med Trupeer AI SOP-værktøjet dækkes både de tekniske gennemgange til ingeniørerne og de tværfunktionelle standardprocedurer (SOP'er), som ingeniørteams overleverer til andre dele af organisationen.