Piattaforma di documentazione centralizzata per i team tecnici

La maggior parte dei team di ingegneria non ha effettivamente bisogno di una nuova piattaforma di documentazione centralizzata. Ne hanno già una (Confluence, Notion, GitHub wiki, un portale per sviluppatori interno). Ciò di cui hanno bisogno è un modo per popolarla con documentazione tecnica sempre aggiornata. Lo strumento di documentazione tecnica di Trupeer AI registra un flusso di lavoro una sola volta e produce un video esplicativo impeccabile insieme a una guida tecnica scritta, pronta per essere incorporata in qualsiasi strumento il team utilizzi già come livello di documentazione centrale. Il collo di bottiglia per la maggior parte dei documenti tecnici è la produzione, non l'archiviazione.

• Registra un flusso di lavoro tecnico una sola volta. Ottieni un video impeccabile e una guida tecnica scritta nello stesso processo.

• Incorpora l'output in qualsiasi piattaforma di documentazione centralizzata esistente: Confluence, Notion, GitHub wiki, portale interno per sviluppatori.

• Aggiorna registrando nuovamente solo il passaggio modificato. Il resto della documentazione tecnica rimane invariato.

• Traduci la documentazione tecnica in oltre 65 lingue per i team di ingegneria globali.

• Condividi tramite un link a una Pagina Condivisa personalizzata che il team può pubblicare su Slack, incorporare in qualsiasi wiki o passare all'assistenza.

Cosa produce Trupeer AI per la documentazione tecnica

Un ingegnere registra una spiegazione a schermo di una distribuzione, di una sessione di debug, di una procedura di risposta agli incidenti o di qualsiasi altro flusso di lavoro tecnico. Trupeer AI si occupa della post-produzione. I intercalari e i momenti del tipo "ehm, fammi trovare la scheda giusta" vengono rimossi. I tremolii del cursore e le transizioni di zoom vengono fluidificati. Una bozza del video e una bozza della guida tecnica scritta arrivano insieme, in modo che il team non debba mantenere due fonti di verità separate per la stessa procedura.

L'output video è in formato MP4, pronto per essere incorporato in qualsiasi software di documentazione tecnica. L'output del documento è in formato PDF o Word, pronto per il wiki di ingegneria o per essere consegnato a un revisore. Il kit del brand si applica automaticamente: il logo aziendale, i colori, i caratteri e le diapositive di introduzione e chiusura corrispondono al resto della libreria di documentazione tecnica. Il glossario personalizzato gestisce i nomi dei prodotti interni, i nomi degli strumenti e i nomi delle API che altrimenti l'IA non saprebbe come scrivere o pronunciare, il che conta più per i contenuti tecnici che per qualsiasi altro tipo di documentazione. Lo strato di registrazione dello schermo AI gestisce l'evidenziazione del cursore, la messa a fuoco dell'area e lo zoom automatico sulle interazioni della UI, ovvero ciò che la maggior parte degli strumenti di scrittura tecnica ignora o esegue male.

Come funziona lo strumento di documentazione tecnica in tre passaggi

L'intero flusso richiede una sola registrazione e produce documentazione tecnica pronta per il rilascio. Nessuno script di preparazione, nessun passaggio di scrittura tecnica separato, nessun arretrato di documentazione da smaltire nei due trimestri successivi.

Passaggio 1: Registra il flusso di lavoro tecnico

Avvia la registrazione nel browser, acquisisci il flusso di lavoro così come viene effettivamente eseguito o carica una registrazione dello schermo esistente. L'IA lavora su ciò che viene registrato. Registrare una distribuzione di 12 minuti è più veloce che scrivere a mente un runbook di 4 pagine, e il risultato è più accurato perché la documentazione rispecchia ciò che l'ingegnere ha effettivamente fatto, non ciò che ricorda di aver fatto.

Passaggio 2: Trupeer AI genera il video e la guida tecnica scritta

I intercalari vengono rimossi. Gli effetti di zoom e del cursore vengono aggiunti laddove aiutano lo spettatore a seguire ciò che accade sullo schermo. Una bozza di video e una bozza di guida tecnica appaiono insieme nell'editor. Si applica il glossario personalizzato, in modo che i nomi degli strumenti interni, gli endpoint API e i nomi dei prodotti siano scritti e pronunciati correttamente in entrambi gli output.

Passaggio 3: Brandizza, traduci e invia al tuo livello di centralizzazione esistente

Applica il kit del brand in modo che il logo aziendale, i colori e le diapositive di introduzione/chiusura corrispondano al resto della libreria di documentazione ingegneristica. Traduci nelle lingue parlate dal team di ingegneria globale (spagnolo, mandarino, hindi, portoghese o una qualsiasi delle oltre 65 opzioni). Quindi, invia tramite un link a una Pagina Condivisa che il team può incorporare in Confluence, Notion, nel wiki di GitHub, nel portale sviluppatori interno o in qualsiasi altra piattaforma di documentazione centralizzata già in uso.

Chi utilizza effettivamente Trupeer AI per la documentazione tecnica

La persona che apre questo strumento è solitamente un tech lead, un engineering manager o un DevOps lead in un'azienda in cui la "documentazione" è stata inserita tra gli OKR per almeno due trimestri consecutivi. Costantemente, il team di ingegneria sa cosa deve essere documentato. Ciò che manca è qualcuno disposto a passare una settimana a scrivere ciò che potrebbe registrare in 30 minuti. Trupeer AI colma il divario tra il sapere cosa dovrebbe essere documentato e il produrre effettivamente la documentazione.

Lo stesso flusso di lavoro si ritrova in diversi ruoli. I team SRE e DevOps lo usano per i runbook di risposta agli incidenti, le procedure di distribuzione e le panoramiche dell'infrastruttura. I team di platform engineering lo usano per la documentazione degli strumenti interni che spiega come funzionano effettivamente i sistemi sviluppati in casa. Gli engineering manager lo usano per inviare la documentazione di onboarding per i nuovi assunti, coprendo la configurazione dell'ambiente, le convenzioni della codebase e gli strumenti specifici del team. I team addetti alla developer experience lo usano per creare documentazione tecnica per le API interne e le librerie condivise da cui dipende il resto dell'azienda. Alcuni team lo considerano un sostituto dell'assunzione di un redattore tecnico; altri lo usano affiancandolo ad esso per moltiplicare l'output di quella persona.

Casi d'uso della documentazione tecnica gestiti da Trupeer AI

La documentazione tecnica copre solitamente quattro tipi di contenuti: come funziona qualcosa, come fare qualcosa, cosa è successo quando qualcosa si è rotto e dove si trovano i confini tra i sistemi. Trupeer AI si occupa di tutti e quattro attraverso lo stesso flusso che va dalla registrazione al documento. Panoramiche di distribuzione, guide alla configurazione dell'ambiente, post-mortem degli incidenti e panoramiche dell'architettura iniziano tutti come una registrazione dello schermo e finiscono come un video impeccabile completato da una guida tecnica scritta. Quello che una volta richiedeva un modello di scrittura tecnica, un modello scaricato per documentazione tecnica, uno dei modelli standard di scrittura tecnica da una ricerca Google o un file Word di modello di documentazione tecnica generico, diventa qualsiasi cosa l'ingegnere voglia produrre, strutturato automaticamente dall'intelligenza artificiale. I team che in precedenza valutavano software di scrittura tecnica separati solo per ottenere un modello utilizzabile di solito abbandonano quel livello una volta implementato Trupeer.

Per la documentazione tecnica del software, il caso d'uso che ripaga più rapidamente è la panoramica degli strumenti interni. Ogni team di ingegneria ha almeno una manciata di strumenti sviluppati internamente che nessuno al di fuori del team sa come usare. Registrare l'uso effettivo di tali strumenti e generare sia il video che la documentazione scritta in un unico processo significa che l'ingegnere successivo che ha bisogno di utilizzare lo strumento non deve contattare su Slack il team che lo ha creato. Lo stesso schema si applica alla documentazione di progettazione tecnica: invece di redigere la progettazione a posteriori, si registra la riunione di revisione del progetto e si lascia che Trupeer AI generi il documento tecnico strutturato a partire da essa. La redazione di report tecnici per post-mortem e analisi delle cause principali funziona allo stesso modo: registra la sessione di analisi, genera il documento, invialo.

L'IA per la scrittura tecnica si guadagna il suo spazio quando il team si rende conto di poter aggiornare la documentazione tecnica esistente registrando nuovamente, anziché trattare ogni aggiornamento come una riscrittura completa. La stessa logica si applica più ampiamente alla scrittura di contenuti tecnici. I team di ingegneria smettono di evitare la documentazione quando il costo per produrla scende al di sotto del costo di spiegare la stessa cosa su Slack quattro volte per trimestre. Questa transizione è l'effettivo cambiamento strutturale che una piattaforma di documentazione centralizzata per i team tecnici dovrebbe consentire, ed è il divario che la maggior parte delle piattaforme lascia da risolvere al team stesso. Trupeer AI è lo strumento a cui la maggior parte dei team ricorre come esempio di documentazione tecnica del software, perché l'output è sufficientemente concreto da essere utilizzato come riferimento per definire l'aspetto reale di una buona scrittura e documentazione tecnica.

Dove si colloca Trupeer AI rispetto a Confluence, Notion, GitHub wiki e altri strumenti di centralizzazione

Trupeer AI non sostituisce lo strato di centralizzazione. Il wiki rimane il wiki. Confluence rimane il luogo in care risiede la documentazione di ogni team. Notion rimane la knowledge base interna del team di ingegneria. Il wiki di GitHub rimane l'archivio della documentazione adiacente al repository. Il portale degli sviluppatori interno rimane la fonte canonica di verità. Trupeer AI si colloca un passaggio prima nel flusso di lavoro, dove i contenuti della documentazione vengono effettivamente prodotti, e invia l'output sotto forma di link a una Pagina Condivisa che si incorpora in uno qualsiasi di questi livelli di centralizzazione esistenti senza modificare la configurazione attuale del team.

La maggior parte dei team di ingegneria ha già investito nello strumento di centralizzazione preferito. Non vogliono migrare, vogliono che lo strumento esistente contenga effettivamente documentazione aggiornata. Il link alla Pagina Condivisa di Trupeer AI è il meccanismo che colma questo divario: sia il video che il documento si aggiornano quando si aggiorna la registrazione sottostante, il che significa che chiunque abbia il link incorporato nel wiki del proprio team visualizza automaticamente la versione corrente. Il wiki rimane il livello di archiviazione e di ricerca. Trupeer AI gestisce la produzione a monte e la manutenzione continua, che è ciò che la maggior parte delle piattaforme di centralizzazione costringe i team a risolvere da soli.

Aggiornamenti: registra nuovamente il passaggio modificato, mantieni intatto il resto della documentazione tecnica

La documentazione tecnica invecchia più rapidamente di qualsiasi altra perché i sistemi sottostanti cambiano settimanalmente. Un processo di distribuzione cambia quando il team migra a una nuova piattaforma CI/CD. Il runbook degli incidenti cambia quando cambia il fornitore del database. Le guide di onboarding cambiano quando il team adotta un nuovo IDE o passa a un diverso strumento di revisione del codice. La maggior parte degli strumenti di documentazione costringe il team a riscrivere da zero le sezioni interessate ogni volta. Trupeer AI gestisce gli aggiornamenti registrando nuovamente solo il passaggio modificato.

Registrare nuovamente è più veloce che riscrivere. L'ingegnere che ha originariamente registrato il flusso di lavoro registra la nuova versione del passaggio che è cambiato. L'IA rielabora solo quel segmento. Sia il video che la guida tecnica scritta si aggiornano sul momento. Qualsiasi link alla Pagina Condivisa distribuito dal team lo scorso trimestre ora indirizzerà alla versione corrente, con il passaggio aggiornato integrato nel resto della documentazione. Chiunque abbia salvato il link originale nei preferiti o lo abbia incorporato nel wiki del team riceverà i nuovi contenuti senza alcuna ricerca manuale. Questo modello di aggiornamento è ciò che consente alla documentazione tecnica di rimanere effettivamente utilizzabile nel corso dei mesi e degli anni in cui i sistemi sottostanti continuano a cambiare. Abbinare il generatore al creatore di SOP di Trupeer AI copre le procedure operative standard che stanno alla base dei flussi di lavoro tecnici registrati.