🥇Progettazione in Confluence

Ciao a tutti!

Mi chiamo Masha e lavoro come ingegnere della qualità nel gruppo Tinkoff. Il lavoro nel QA implica molte comunicazioni con diverse persone da vari team, e io, che sono stata anche manager e docente di programmi educativi, ho avuto una rete di comunicazione molto ampia. E a un certo punto ho esploso: ho capito che non potevo più, più, più riempire tonnellate di tabelle e documenti illeggibili.

Sicuramente ognuno di voi ora si sta immaginando ciò di cui parlo e ha sudato freddo: liste di cognomi senza ordine alfabetico, tabelle con centinaia di colonne e formattazione disordinata, tabelle con migliaia di righe in cui bisogna strisciare il dito sulla rotellina del mouse per vedere il titolo, tonnellate di pagine senza numerazione, centinaia di e-mail inviate tra di noi con dati da analizzare e sistematizzare e da infilare in altrettante tabelle illeggibili.

E, quando ho preso un po' di distanza, ho deciso di scrivere questo articolo. Parlerò di come si possa gestire in modo adeguato (e talvolta anche comodo) la documentazione non legata al prodotto. Spero che l'articolo si diffonda in rete e che il livello di caos nei reparti vicini allo sviluppo si abbassi, rendendo le persone (me compresa) un po' più felici.

Strumenti

La documentazione del prodotto è spesso conservata accanto al codice, ed è una cosa positiva. La documentazione non legata al prodotto, invece, viene solitamente dispersa. Spesso, le persone cercano di trasferire informazioni da vari luoghi in Confluence, e noi non facciamo eccezione. Quindi, parlerò di questo in seguito.

In effetti, Confluence è un avanzato motore wiki. Permette di lavorare con i dati in diverse modalità di visualizzazione: testo formattato, tabelle, vari diagrammi. È uno strumento molto interessante e potente, ma se non si sa come utilizzarlo correttamente, si rischia di ottenere un'altra discarica di documenti illeggibili. Vi insegnerò a prepararlo!

Macro

Quasi tutta la magia di Confluence si basa sui macro. Ce ne sono molti e possono essere combinati tra loro. Esistono versioni a pagamento e gratuite; seguiranno vari esempi di macro con link alla loro documentazione.

L'interfaccia per lavorare con i macro è estremamente semplice. Per aggiungere un macro, è necessario fare clic sul segno più e selezionare l'elemento desiderato dalla lista.

Se il macro è autonomo, ovvero non richiede l'inserimento di qualcos'altro al suo interno, appare come un blocco.

Se per il funzionamento del macro è necessario inserire qualcosa all'interno, appare come un riquadro.

In questo modo, puoi inserire all'interno di un riquadro quanti più elementi di altri desideri, purché ci sia un senso logico nella tua piramide.

Ogni macro presenta un'anteprima: qui puoi immediatamente vedere se hai compilato e configurato correttamente il macro.

Modelli

Oltre ai macro, esiste uno strumento molto utile di completamento automatico del contenuto: il modello.
I modelli possono essere utilizzati durante la creazione di qualsiasi pagina: basta fare clic sui tre puntini accanto al pulsante "Crea" e selezionare il modello desiderato.

In questo modo, verrà aggiunto alla pagina creata tutto il contenuto presente nel modello.

Chiunque può creare pagine a partire da modelli, ma solo chi ha i diritti può creare o modificare i modelli stessi. All'interno di un modello possono essere aggiunte istruzioni aggiuntive su come gestire la pagina.

La magia delle tabelle

In effetti, come tecnico, amo teneramente le tabelle e posso inserire quasi qualsiasi informazione al loro interno (anche se non è sempre efficace). Le tabelle stesse sono chiare, strutturate, scalabili, magiche!

Ma anche una meravigliosa entità come la tabella può essere rovinata. Oppure può essere usata con successo e persino migliorata. Di questo parlerò qui di seguito.

Filtraggio (plugin a pagamento)

Qualsiasi tabella enorme e illeggibile può diventare un po' meno enorme e un po' più leggibile grazie al filtraggio. A tal fine, si può utilizzare un macro a pagamento. «Filtro tabelle».

All'interno di questo macro bisogna inserire la tabella (si può anche usare la più brutta, l'importante è inserirla per intero). Nel macro è possibile scegliere le colonne da filtrare tramite un menu a discesa, filtro testuale, numerico e filtro per date.

Immagina che tutte le informazioni sui candidati per tutte le posizioni siano registrate in un elenco tabellare. Naturalmente, non ordinato: le persone non partecipano ai colloqui in ordine alfabetico. E tu devi capire se hai già intervistato un determinato candidato. Basta inserire questo caos in un macro filtro, aggiungere un filtro testuale per il cognome — ed ecco, hai le informazioni sullo schermo.

È importante notare che filtrare enormi tabelle può influenzare le prestazioni del sistema e i tempi di caricamento delle pagine, quindi inserire un'enorme tabella in un filtro è una soluzione temporanea; è meglio strutturare un processo in cui le persone non debbano creare enormi tabelle illeggibili (un esempio di processo sarà alla fine dell'articolo).

Ordinamento (plugin a pagamento)

Con il magico macro «Filtro tabelle» puoi anche impostare un ordinamento predefinito per qualsiasi colonna e numerare le righe. Oppure fare clic su qualsiasi colonna della tabella inserita nel macro filtro, e si attiverà l'ordinamento per quella colonna.

Ad esempio, hai la stessa tabella con i candidati e devi stimare quante interviste sono state effettuate in un mese specifico: ordina per data e goditi il risultato.

Tabelle pivot (plugin a pagamento)

Passiamo ora a un caso più interessante. Immagina che la tua tabella sia enorme e tu debba calcolare qualcosa su di essa. Certamente, puoi copiarla in Excel, fare i calcoli necessari e caricare i dati nuovamente in Confluence. Oppure puoi applicare una volta per tutte la macro «Tabella pivot» e ottenere lo stesso risultato, ma anche in modo aggiornato.

Ad esempio: hai una tabella che raccoglie i dati di tutti i dipendenti, indicando dove si trovano geograficamente e quali sono i loro ruoli. Per contare quante persone ci sono in ogni città, devi selezionare nella macro «Tabella pivot» la riga su cui aggregare i dati (posizione) e il tipo di operazione (somma).

Naturalmente, puoi raggruppare per più criteri contemporaneamente, puoi visualizzare tutte le possibilità. nella documentazione.

Diagrammi (plugin a pagamento)

Come già detto, non tutti amano le tabelle tanto quanto me. Purtroppo, la maggior parte dei manager le detesta. Tuttavia, tutti adorano i diagrammi colorati e vivaci.
I creatori di Confluence ne erano sicuramente a conoscenza (probabilmente hanno anche loro capi che amano report e diagrammi, non si può farne a meno). Quindi, è possibile sfruttare il magico macro «Diagramma da tabella». In questo macro bisogna inserire la tabella pivot del punto precedente, ed ecco fatto — i vostri grigi e noiosi dati saranno splendidamente visualizzati.

Naturalmente, anche questo macro ha delle impostazioni. Il link alla documentazione di qualsiasi macro può essere trovato in modalità di modifica di quest'ultima.

Semplicità di aggregazione

Le informazioni nei punti precedenti non saranno state per voi una rivelazione. Ma ora sapete sicuramente come usare i macro, e posso passare a una parte più interessante dell'articolo.

Etichette

È problematico quando le persone memorizzano informazioni in un unico articolo non strutturato o in un enorme foglio di calcolo. Anche peggio è quando parti di queste informazioni non solo sono presentate in modo illeggibile, ma sono anche disperse nei meandri di Confluence. Fortunatamente, è possibile raccogliere le informazioni disperse in un unico posto. Per fare questo, è necessario utilizzare etichette (simili ai tag che tutti conosciamo dai social media).

Puoi aggiungere un numero illimitato di etichette a qualsiasi pagina. Se clicchi su un'etichetta, verrai indirizzato a una pagina di aggregazione, dove troverai link a tutti i materiali con quell'etichetta, nonché un insieme di etichette correlate. Le etichette correlate sono quelle che spesso compaiono sulla stessa pagina.

Proprietà delle pagine

Puoi aggiungere un'altra macro interessante a una pagina per strutturare le informazioni — «Proprietà delle pagine». All'interno di essa devi fornire una tabella di due colonne, la prima sarà la chiave e la seconda il valore della proprietà. Inoltre, la macro può essere nascosta dalla pagina, in modo che non disturbi la lettura del contenuto, ma la pagina sarà comunque contrassegnata con le chiavi necessarie.

Attenzione all'ID: è utile assegnarlo per associare diversi gruppi di proprietà a pagine differenti (o anche a gruppi di proprietà diversi su una sola pagina).

Report

È possibile raccogliere report per etichetta. Ad esempio, il macro «Report sul contenuto» raccoglie tutte le pagine con un determinato insieme di etichette.

Ma un report più interessante è il macro «Report sulle proprietà della pagina». Anche questo raccoglie tutte le pagine con un certo insieme di etichette, ma non si limita a elencarle, bensì compila una tabella (capite il legame con l'inizio dell'articolo?), in cui le colonne rappresentano le chiavi delle proprietà della pagina.

Si ottiene una tabella riepilogativa con informazioni provenienti da diverse fonti. È piacevole notare che ha funzioni comode: layout reattivo, ordinamento per qualsiasi colonna. Inoltre, questa tabella di report può essere configurata all'interno del macro.

Nella configurazione è possibile rimuovere alcune colonne dal report, impostare uno stato predefinito o il numero di record visualizzati. Inoltre, è possibile impostare l'ID della proprietà della pagina per vedere solo le informazioni necessarie.

Ad esempio, hai diverse pagine dedicate ai dipendenti, ciascuna con un insieme di proprietà riguardanti la persona: il suo livello, la sua posizione, quando è entrato nel team e così via. Queste proprietà sono contrassegnate ID = employee_inf. E c'è un secondo insieme di proprietà sulla stessa pagina, che raccoglie informazioni sulla persona come parte del team: quale ruolo svolge, in quale team si trova e così via. Queste proprietà sono contrassegnate ID = team_inf. Quindi, durante la generazione del rapporto, puoi visualizzare solo le informazioni relative a un singolo ID oppure a entrambi — a seconda di ciò che è più comodo.

Il bello di questo approccio è che ognuno può creare la propria tabella informativa personalizzata, che non presenterà duplicati e si aggiornerà automaticamente quando viene aggiornato il contenuto principale della pagina. Ad esempio, per un team leader, non è rilevante sapere quando i suoi sviluppatori sono stati assunti, ma è importante quale ruolo ciascuno di loro svolge all'interno del team. Quindi il team leader creerà un rapporto per il team. Un contabile, invece, non è affatto interessato ai ruoli, ma agli incarichi — redigerà un rapporto per le posizioni. In questo modo, la fonte delle informazioni non verrà duplicata o trasferita.

Processo finale

Istruzione

Possiamo quindi strutturare e aggregare efficacemente le informazioni in Confluence utilizzando i macro. Ma idealmente è necessario fare in modo che le nuove informazioni siano subito strutturate e integrate in tutti i meccanismi di aggregazione già esistenti.

Qui entra in gioco la combinazione di macro e modelli. Per incentivare le persone a creare nuove pagine nel formato desiderato, puoi utilizzare il macro "Crea da modello". Questo aggiunge un pulsante alla pagina, che, una volta cliccato, crea una nuova pagina utilizzando il modello desiderato. In questo modo, incoraggi le persone a lavorare immediatamente nel formato che necessiti.

Nel modello da cui consenti la creazione della pagina, devi previamente aggiungere etichette, il macro "Proprietà della pagina" e una tabella delle proprietà necessarie. Ti consiglio anche di includere istruzioni su quali valori dovrebbero essere utilizzati per riempire la pagina e i valori delle proprietà.

Il processo finale sarà quindi il seguente:

Crei un modello per informazioni di un certo tipo.
In questo modello aggiungi etichette e proprietà della pagina nel macro.
In qualsiasi luogo conveniente, crei una pagina principale con un pulsante, cliccando sul quale si genera una pagina figlia da un modello.
Consenti agli utenti di accedere alla pagina principale, che potrebbero generare le informazioni necessarie (secondo il modello richiesto, premendo il pulsante).
Raccogli un report sulle proprietà della pagina attraverso le etichette che hai specificato nel modello.
Ti godi il fatto che hai tutte le informazioni necessarie in un formato conveniente.

Problemi inaspettati

Come ingegnere della qualità, posso affermare con certezza che nulla è perfetto nel mondo. Anche le tabelle divine non sono prive di imperfezioni. E nel processo sopra menzionato ci sono insidie.

Se decidi di cambiare i nomi o la composizione delle proprietà della pagina, dovrai aggiornare tutti gli oggetti già creati affinché i loro dati vengano correttamente trasferiti nel report riassuntivo. È un peccato, ma d'altra parte, costringe a pensare attentamente all'«architettura» del tuo insieme di informazioni, il che è una sfida piuttosto interessante.
Dovrai scrivere una buona quantità di istruzioni su come compilare le tabelle informative e utilizzare i tag. D'altra parte, puoi semplicemente inviare questa articolo a tutte le persone necessarie.

Esempio di archiviazione della documentazione non relativa al prodotto

Attraverso il processo descritto sopra, è possibile organizzare l'archiviazione di quasi qualsiasi informazione. Il bello dell'approccio è che è universale: quando gli utenti si abituano, smettono di generare confusione. Inoltre, un grande (ma non gratuito) vantaggio è la possibilità di raccogliere statistiche variegate in tempo reale e crearne bellissimi diagrammi.

Fornirò un esempio del nostro processo di gestione delle informazioni sul team.

Per ogni persona nel team, abbiamo deciso di creare una scheda dipendente. Pertanto, abbiamo un modello according al quale ogni nuova persona crea questa scheda e inserisce tutte le informazioni personali.

Come puoi vedere, abbiamo una tabella di proprietà dettagliata e ci sono istruzioni su come gestire questa pagina. Alcuni tag vengono impostati dagli stessi dipendenti seguendo le istruzioni; nel modello ci sono solo i principali: tag scheda employee-card, tag direzione direction-involve e tag del team team-qa.

Alla fine, dopo che ognuno ha creato la propria scheda, si ottiene una tabella completa con le informazioni sui dipendenti. Queste informazioni possono essere utilizzate in vari punti. I manager delle risorse possono raccogliere tabelle generali, mentre i team leader possono creare tabelle per il team, aggiungendo i tag del team alla selezione.

Attraverso i tag si possono vedere vari riepiloghi, ad esempio per qa-upgrade-plan verranno visualizzate tutte le attività per lo sviluppo del QA. Ogni persona gestisce nella propria scheda dipendente una storia importante e il proprio piano di sviluppo, creando una pagina interna dal template dei piani di sviluppo.