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

Scopri come Alex ha utilizzato i Documenti per permettere al suo team di migliorare le funzionalità più velocemente.

Conosci Alex

Alex è uno sviluppatore senior in una compagnia di software basata sul cloud. Scoprono che alcune funzionalità hanno una documentazione molto limitata.

Alex si accorge che il team impiega molto tempo a investigare il funzionamento delle funzionalità direttamente dal codice del loro software. Questo rallenta la capacità del team di migliorare le funzionalità esistenti.

La sfida

I team di prodotto e ingegneria lavorano secondo una tempistica molto stretta per rilasciare le funzionalità nel prodotto. Gli sviluppatori hanno tempo molto limitato per poter creare documentazione sulle nuove funzionalità.

Il team non ha tempo per mantenere la documentazione mentre una funzionalità viene migliorata nel tempo e i bug vengono risolti.

Alcuni sviluppatori più nuovi sono frustrati dalla mancanza di documentazione. Trovano difficile apprendere efficacemente il prodotto.

Altri sviluppatori sentono di passare più tempo a rispondere a domande invece di risolvere problemi e scrivere codice migliore.

La soluzione

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

Crea la struttura del documento e della pagina

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

Utilizzare le pagine all'interno di un documento consente al team di trovare rapidamente le risposte pertinenti senza cercare e sfogliare 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. Riassunto del prodotto

2. Codice front end

3. Codice back end

4. Infrastruttura

5. App per dispositivi mobili

6. Test e QA

7. FAQ e Risoluzione dei problemi

Consiglio: Cerca pagine specifiche o contenuti all'interno di un Doc usando la funzione di Ricerca!

Titoli

In ogni pagina, Alex imposta dei titoli così è chiaro al team di sviluppo quali informazioni inserire e dove.

Riassunto del prodotto

• Breve descrizione del prodotto

• Schema delle funzionalità

• Casi d'uso

• Progettazione dell'interfaccia utente

Front End

• Elementi dell'interfaccia utente

• Stili

• Suggerimenti contestuali

Back End

• Percorsi API

• Schema del database

Dispositivo mobile

• iOS

• Android

Test e QA

• Criteri di accettazione

• Test automatizzati QA

Formattazione

Alex utilizza una combinazione delle opzioni di formattazione disponibili nei Documenti ClickUp per conferire alla loro documentazione un aspetto e una sensazione coerenti.

Codice in linea e blocchi di codice

Alex utilizza i backtick ( `` ) per formattare il testo come codice in linea per visualizzare singole righe di codice, come mostrato nell'esempio qui sotto:

Per frammenti di codice più lunghi, Alex utilizza la Formattazione del Blocco di Codice ( /co ) come mostrato di seguito:

Opzioni di formattazione dei blocchi di codice

Imposta il tuo blocco di codice per utilizzare il linguaggio di programmazione che preferisci!

1. Passa il mouse sull'angolo in alto a destra

2. Seleziona la tua lingua preferita

Collega e incorpora contenuti

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

Sta prendendo forma, ma il Riassunto del Prodotto è ancora vuoto.

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

Alex utilizza la menzione @@ per collegare l'attività epica alla roadmap del team.

Creare un modello

Alex salva la struttura del Doc come modello affinché il team possa creare rapidamente e facilmente un Doc con le sottopagine e i titoli per altre funzionalità.

1. Clicca sull'icona delle impostazioni del Documento nella barra laterale destra

2. Seleziona Salva come Modello

Alex compila un esempio di documento usando il modello affinché il team abbia un esempio eccellente di documentazione da utilizzare come riferimento.

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

Prova concettuale

Alex presenta il concetto di modello di documento al team di ingegneria durante la prossima riunione di squadra. Gli altri sviluppatori apprezzano l'esempio dettagliato di documentazione di Alex!

Il team è preoccupato per il tempo che potrebbe essere necessario per compilare i dettagli. Alex lancia una sfida: scegliere una funzionalità per dimostrare quanto sia rapido creare documentazione.

Il team decide su una funzionalità. Alex crea un Documento, applica il modello usando il comando di barra /temp e condivide il link con tutti i partecipanti alla chiamata.

Alcuni sviluppatori iniziano a modificare collaborativamente il Doc con Alex. Ognuno completa le pagine e le sezioni che conosce meglio.

L'intero team rimane piacevolmente sorpreso quando, dopo solo 20 minuti, hanno creato una bozza abbastanza completa della documentazione.

Il risultato

Il team accetta di testare il modello e la documentazione di Alex. Nel loro prossimo Sprint, alcuni sviluppatori dedicano 30 minuti a compilare la documentazione per la funzionalità principale.

La documentazione non è ancora completa. È presente un abbozzo con i dettagli necessari per aiutare altri sviluppatori a comprendere e migliorare la funzionalità.

Dopo alcune settimane, l'abitudine di scrivere documentazione è diventata una parte importante delle responsabilità del team di ingegneria.

Con alcuni aggiustamenti e miglioramenti al modello di Alex, il tempo speso per creare e mantenere la documentazione diminuisce.

Alex invia una ricerca e scopre che:

• I nuovi sviluppatori si sentono più sicuri nel lavorare con il codice quando è disponibile della documentazione

• Gli sviluppatori esperti notano meno domande dai loro colleghi e dai team di supporto clienti

È un grande successo per il team di ingegneria! Durante un evento di squadra, Alex riceve il titolo onorario di "Bibliotecario Residente e custode della conoscenza".