Dokumentační nástroj pro vzdálené inženýrské týmy

Trupeer AI je nástroj pro tvorbu interaktivních návodů a dokumentace pro vzdálené vývojářské týmy, které se nemohou jen tak naklonit a zeptat se kolegy vedle sebe. Seniorní vývojář jednou nahraje vysvětlení (jak vlastně funguje nasazovací pipeline, proč tato služba řeší opakované pokusy právě takto, co dělá ta nejsložitější část kódu a proč je tak složitá) a Trupeer AI v rámci jednoho úkolu vygeneruje jak video, korespondující s nahrávkou, tak písemný technický dokument. Ostatní vývojáři pracující v různých časových pásmech a kancelářích se na něj pak podívají a přečtou si ho asynchronně. Distribuované vývojářské týmy netrpí ani tak nedostatkem README souborů, jako spíše chybějícím vysvětlením, co za daným README stojí – což je přesně to, co seniornímu vývojáři trvá celé odpoledne sepsat a na co nikdo nikdy nemá čas.

• Seniorní vývojář nahraje ukázku. Video i písemná technická dokumentace dorazí současně.

• Navrženo pro asynchronní workflow ve více časových pásmech, ve kterém distribuované vývojářské týmy již fungují.

• Překládejte dokumentaci do více než 65 jazyků pro vývojářské týmy v USA, Indii, Evropě a Latinské Americe.

• Funguje po boku stávající týmové wiki, repozitáře kódu a API dokumentace. Žádnou z těchto platforem nenahrazuje.

• Aktualizujte pouhým přehráním změněného kroku. Dokumentace k architektuře tak nikdy nezastará.

Co Trupeer AI přináší vývojářským týmům

Seniorní vývojář spustí nahrávání obrazovky. Provede tým nasazením produkční služby, laděním staging prostředí nebo vysvětlí návrhové rozhodnutí pro frontu zpráv, které tým učinil v roce 2024. Trupeer AI se postará o postprodukci. Odstraní výplňová slova. Efekty přiblížení zvýrazní příkaz v terminálu, oblast v IDE nebo ovládací panel, na který se další vývojář potřebuje podívat. V jednom rozhraní se pak objeví koncept videa i koncept písemného technického dokumentu se snímky obrazovky a očíslovanými kroky.

Výstupy se exportují jako video ve formátu MP4 a dokument ve formátu PDF nebo Word. Dokument je to, co si člověk přečte na wiki nebo vloží do Notion či Confluence. Videa jsou to, co vývojáři sledují v centru nápovědy, co mají vložené v ticketu v Linear nebo co sdílejí prostřednictvím odkazu na sdílenou stránku. Obojí vzniká ze stejné nahrávky bez nutnosti dalších úprav. Šablona značky (brand kit) aplikuje úvodní a závěrečné snímky specifické pro daný vývojový tým a vlastní glosář se postará o interní názvy služeb, názvy komponent infrastruktury a zkratky, které by umělá inteligence jinak nenapsala správně.

Jak nástroj pro tvorbu technické dokumentace funguje ve třech krocích

Celý proces pokrývají tři kroky: nahrajte to, co už má seniorní vývojář v hlavě, nechte AI vygenerovat oba formáty a sdílejte je prostřednictvím odkazu, který zbytek týmu snadno najde bez ohledu na časové pásmo.

Krok 1: Nahrajte vysvětlení

Spusťte nahrávání obrazovky v prohlížeči, ve vývojovém prostředí (IDE) týmu nebo v terminálu. Seniorní vývojář mluví o své práci stejně, jako by to vysvětloval nováčkovi při osobním setkání. Pět až deset minut nahrávání obvykle stačí na vysvětlení architektury nebo postup při nasazení. AI pracuje s tím, co je nahráno, takže vývojář nemusí psát žádný koncept ani připravovat prezentaci.

Krok 2: AI vygeneruje video a písemný technický dokument

Výplňová slova a momenty typu „moment, jen najdu ten soubor“ se automaticky odstraní. Efekty přiblížení zvýrazní důležité části obrazovky (cestu k souboru, výstup z terminálu, diff v rámci revize kódu). V editoru se společně objeví koncept videa i písemného technického dokumentu. Vlastní glosář zachytí interní názvy služeb a zkratky komponent dříve, než dojde k jejich chybnému přepisu.

Krok 3: Branding, překlad, sdílení

Použijte šablonu značky, aby interní vývojové dokumenty vypadaly v celé knihovně týmu konzistentně. Přeložte je do jazyků, které váš tým skutečně používá: do španělštiny pro pobočku v Mexico City, do hindštiny pro tým v Bengalúru, do portugalštiny pro São Paulo. Sdílejte vše prostřednictvím odkazu na sdílenou stránku, která bude uložena na wiki, v onboardingovém dokumentu týmu nebo ji vložte přímo do kanálů na Slacku, kde ji vývojáři najdou, aniž by museli přerušovat práci.

Kdo tento nástroj pro tvorbu technické dokumentace využívá

Tento nástroj obvykle otevírá vedoucí vývojář (staff engineer), manažer vývoje nebo technický lídr ve firmách s hybridním režimem či s prací na dálku, kde lidé působí alespoň ve dvou časových pásmech. Využijí ho, když nastoupí nový člověk a samotné README nestačí, když tým učiní netriviální architektonické rozhodnutí, jehož zdůvodnění stojí za zaznamenání, nebo když pohotovostní příručka (runbook) musí reálně vysvětlit, co dělat ve tři ráno, místo pouhého vypsání příkazů. Některé týmy ho používají rutinně pro každé zásadní rozhodnutí o návrhu, jiné po něm sáhnou jen tehdy, když se objeví mezera v dokumentaci, kterou je třeba vysvětlit.

Stejný postup se uplatňuje napříč rolemi. DevOps a SRE specialisté nahrávají retrospektivy incidentů a průvodce infrastrukturou, které se následně sdílejí s celým vývojovým týmem. Manažeři vývoje nahrávají onboardingové průvodce pro nové zaměstnance, aby se stejné otázky nemusely každý týden řešit v soukromých zprávách. Tech lídři zaznamenávají rozhodnutí o architektuře, aby budoucí vývojáři věděli, proč systém vypadá tak, jak vypadá. Šéfové vývoje nahrávají mezitýmové novinky (novou interní platformu, migraci služeb, změnu v procesu nasazení), které by jinak vyžadovaly schůzku pro 50 lidí, na kterou nikdo nechce jít.

Typy technického obsahu, které tento nástroj zpracovává

Mezi nejčastější typy obsahu patří: průvodci architekturou a návrhem (proč systém vypadá právě takto), provozní příručky pro nasazení a infrastrukturu (how-to pro nasazení do produkce, jak provést rollback), onboardingoví průvodci (prohlídka codebase, nastavení lokálního vývojového prostředí, první revize kódu), retrospektivy incidentů a analýzy po selhání (co se stalo, co jsme se naučili, co měníme) a vysvětlení k revizi kódu (důvody netriviálního PR). Trupeer AI zvládá všechny tyto typy se stejným procesem od nahrávky k dokumentu. Formát se přizpůsobí: runbook vyžaduje očíslované kroky se snímky obrazovky, vysvětlení architektury vyžaduje video s písemným shrnutím, onboardingový průvodce pak obojí.

V rámci širšího pojetí technické dokumentace vyplňuje Trupeer AI vrstvu vysvětlujícího obsahu, kterou textové wiki nástroje nechávají prázdnou. Vývojová softwarová dokumentace se obvykle dělí do tří vrstev: referenční dokumentace generovaná z kódu (Sphinx, javadoc, OpenAPI), obsah týmové wiki (Confluence, Notion, Slab) a lidmi nahrané průvodce. Většina vývojových týmů má první vrstvu, protože je automatická, a druhou, protože někdo dostal zaplaceno za její sepsání. Třetí vrstva (systémová dokumentace ve vývoji softwaru, dokumentace vývojových projektů, interní dokumentace ve vývoji softwaru) je ta, která vždy zaostává. Trupeer AI umožňuje vytvořit tuto třetí vrstvu tak rychle, že to seniorní vývojář zvládne v pátek odpoledne mezi schůzkami.

Kam Trupeer zapadá vedle wiki systémů, nástrojů na dokumentaci kódu a generátorů API dokumentace

Trupeer AI nenahrazuje týmovou wiki. Confluence, Notion, Slab, GitBook a interní týmové wiki dál dělají to, k čemu slouží. Trupeer AI vytváří nahraný vysvětlující obsah, který se do těchto wiki vkládá jako sdílená stránka po boku psaných článků, které už tým vytvořil.

Trupeer AI rovněž nenahrazuje generátory API dokumentace. Swagger, Stoplight, Redoc, Postman a jakékoli automaticky generované referenční dokumenty OpenAPI nadále spravují dokumentaci na úrovni koncových bodů. Trupeer AI funguje na jiné úrovni: přináší lidské vysvětlení toho, jak bylo API navrženo, jak ho skutečně integrovat a jaká jsou úskalí, která referenční dokumentace neodhalí. Knihovna dokumentace vývojového týmu obvykle vyžaduje obojí – automaticky generované referenční informace i lidský výklad. Trupeer AI řeší pouze druhou jmenovanou část; první zůstává tam, kde je. Stejná logika platí i pro nástroje na úrovni kódu, jako jsou Doxygen, javadoc a systémy inline komentářů, které Trupeer AI spíše doplňuje, než aby jim konkuroval. Pro správu vývojové dokumentace a technickou dokumentaci obecně to znamená, že tým získá vysvětlující vrstvu, aniž by musel rušit cokoli ze svých stávajících řešení.

Aktualizace a překlad pro globálně distribuované vývojářské týmy

Technická dokumentace stárne rychleji, než netechnické týmy očekávají, protože podkladové systémy se mění každý týden. Změna v nasazovací pipeline zneplatní provozní příručku z minulého čtvrtletí, refaktorování architektury učiní dokumentaci návrhu zavádějící a přejmenovaná služba způsobí zmatek v onboardingovém průvodci. Většina týmů to řeší tak, že dokumentaci nechá v tichosti zastarat a na dotazy odpovídá na Slacku pokaždé, když někdo na neaktuální dokument narazí. Trupeer AI řeší aktualizace nahráním pouze té části, ve které došlo ke změně. AI přepracuje pouze tuto pasáž, video i písemný technický dokument se aktualizují přímo na místě a další vývojář, který se podívá na wiki, uvidí aktuální verzi.

U globálně distribuovaných vývojářských týmů překlad odstraňuje bariéry, o kterých se na denních stand-upech nikdo nezmiňuje. Stejné vysvětlení architektury se dostane k týmu v Bengalúru v hindštině, k týmu v Berlíně v němčině a k týmu v São Paulu v portugalštině – ze stejné zdrojové nahrávky a během téhož týdne. Překlad se vztahuje jak na mluvený komentář videa, tak na písemný technický dokument, přičemž je zachována šablona značky, glosář i text na obrazovce. Propojení tohoto postupu tvorby dokumentace s nástrojem na tvorbu standardních operačních postupů (SOP) od Trupeer AI pokrývá jak průvodce určené pro vývojáře, tak mezifunkční standardní operační postupy, které vývojové týmy předávají ostatním částem organizace.