Crea e gestisci rapidamente la documentazione sul tuo codice o sulle funzionalità che hai sviluppato!

Scopri come Alex ha usato i Documenti per aiutare il suo team a migliorare le funzionalità più velocemente.

Chi è Alex

Alex è uno sviluppatore senior in un'azienda software basata sul cloud. Si accorge che alcune funzionalità hanno una documentazione molto scarsa.

Alex nota che il team trascorre molto tempo a esaminare come funzionano le funzionalità direttamente dal codice del software. Questo rallenta la capacità del team di migliorare le funzionalità esistenti.

La sfida

I team di prodotto e di sviluppo lavorano con tempi molto stretti per rilasciare le funzionalità nel prodotto. Gli sviluppatori hanno pochissimo tempo per creare documentazione sulle nuove funzionalità.

Il team non ha tempo di mantenere aggiornata la documentazione man mano che una funzionalità viene migliorata e i bug vengono risolti.

Alcuni sviluppatori più giovani sono frustrati dalla mancanza di documentazione e faticano ad apprendere il prodotto in modo efficace.

Altri sviluppatori hanno la sensazione di trascorrere più tempo a rispondere a domande che a risolvere problemi e scrivere codice migliore.

La soluzione

Alex sta lavorando al miglioramento di una funzionalità che non ha una buona documentazione. Decide di creare un Documento ClickUp con informazioni sulla funzionalità, da usare come materiale di riferimento per gli altri sviluppatori.

Creare il documento e la struttura delle pagine

Alex decide che ogni funzionalità dovrebbe avere il proprio Documento. Quando il team lavora su una funzionalità, tutte le informazioni rilevanti si trovano in un unico documento autonomo.

Usare le pagine all'interno di un Documento permette al team di trovare rapidamente le risposte che cerca, senza dover scorrere Documenti separati.

Alex crea alcune pagine all'interno del Documento per strutturare i contenuti in base a ciò che il team deve sapere e potrebbe cercare.

1. Riepilogo del prodotto
2. Codice front-end
3. Codice back-end
4. Infrastruttura
5. App mobile
6. Test e controllo qualità
7. FAQ e risoluzione dei problemi

Intestazioni

In ogni pagina, Alex aggiunge delle intestazioni così il team di sviluppo sa subito dove inserire le informazioni.

Riepilogo del prodotto

• Brief di prodotto
• Schema della funzionalità
• Casi d'uso
• Design dell'interfaccia

Front-end

• Elementi dell'interfaccia
• Stili
• Tooltip

Back-end

• Route API
• Schema del database

Mobile

• iOS
• Android

Test e controllo qualità

• Criteri di accettazione
• Test automatizzati di controllo qualità

Formattazione

Alex usa una combinazione delle opzioni di formattazione disponibili nei Documenti ClickUp per dare alla documentazione un aspetto coerente.

Codice inline e blocchi di codice

Alex usa i backtick ( \\\\ ) per formattare il testo come codice inline e visualizzare singole righe di codice, come mostrato nell'esempio qui sotto:

Per frammenti di codice più estesi, Alex usa la formattazione dei blocchi di codice ( /co ), come mostrato di seguito:

Opzioni di formattazione dei blocchi di codice

Imposta il blocco di codice sul linguaggio di programmazione che preferisci!

1. Passa il cursore sull'angolo in alto a destra
2. Seleziona il linguaggio preferito

Collegare e incorporare contenuti

Ora il Documento di Alex contiene testo, alcuni screenshot e utili frammenti di codice.

Ha un buon aspetto, ma il riepilogo del prodotto è ancora vuoto.

Il team di prodotto usa Figma per progettare e creare wireframe dell'interfaccia utente. Alex usa il /Slash Command /figma per incorporare il design aggiornato della funzionalità direttamente nella pagina del riepilogo del prodotto.

Alex usa la menzione @@ per collegarsi all'attività Epic nella roadmap del team.

Creare un modello

Alex salva la struttura del Documento come Modello in modo che il team possa creare rapidamente un Documento con le sottopagine e le intestazioni per altre funzionalità.

1. Fai clic sull'icona delle impostazioni del Documento nella barra laterale destra
2. Seleziona Salva come modello

Alex compila un Documento di esempio usando il modello, così il team ha uno standard di riferimento per la documentazione.

Alex crea un nuovo Documento basato sul modello, lo compila e lo condivide con il team.

Prova del concetto

Alex presenta il concetto del modello di Documento al team di sviluppo durante la riunione successiva. Gli altri sviluppatori apprezzano molto l'esempio dettagliato di documentazione di Alex!

Il team è preoccupato per il tempo che potrebbe volerci per compilare tutti i dettagli. Alex li sfida a scegliere una funzionalità, così può mostrare a tutti quanto è veloce creare la documentazione.

Il team sceglie una funzionalità. Alex crea un Documento, applica il modello usando il /Slash Command /temp e condivide il link con tutti i partecipanti alla chiamata.

Alcuni sviluppatori si uniscono e iniziano a modificare il Documento in modo collaborativo con Alex. Ognuno compila le pagine e le sezioni che conosce meglio.

L'intero team è piacevolmente sorpreso quando, dopo soli 20 minuti, ha già una bozza abbastanza completa della documentazione.

Il risultato

Il team decide di mettere alla prova il modello e la documentazione di Alex. Nel Sprint successivo, alcuni sviluppatori dedicano 30 minuti a compilare la documentazione per la funzionalità principale.

La documentazione non è del tutto completa. C'è una bozza di struttura con dettagli sufficienti per aiutare gli altri sviluppatori a iniziare a comprendere e migliorare la funzionalità.

Dopo alcune settimane, scrivere documentazione è diventata un'abitudine consolidata e una parte importante delle responsabilità del team di sviluppo.

Con qualche ritocco e miglioramento al modello di Alex, il tempo dedicato alla creazione e alla manutenzione della documentazione si riduce.

Alex invia un sondaggio e scopre che:

• Gli sviluppatori più giovani si sentono più sicuri nel lavorare con il codice quando è disponibile la documentazione
• Gli sviluppatori esperti ricevono meno domande dai colleghi e dai team di assistenza clienti

È una grande vittoria per il team di sviluppo! Durante un evento del team, Alex riceve il titolo onorario di "Bibliotecario residente e custode del sapere".