🥇Progettazione in Confluence

Ciao a tutti!

Mi chiamo Masha, lavoro come ingegnere della qualità nel gruppo di aziende Tinkoff. Il lavoro di QA prevede molte comunicazioni con persone diverse provenienti da vari team, e io, essendo stata anche manager e docente di programmi educativi, ho avuto una rete di comunicazioni molto ampia. A un certo punto, però, ho avuto un'esplosione: ho capito che non potevo più, non potevo più, non potevo più riempire tonnellate di tabelle e documenti illeggibili.

Sicuramente ognuno di voi ora ha immaginato ciò di cui parlo e ha sudato freddo: elenchi di nomi privi di ordine alfabetico, tabelle con centinaia di colonne con layout disordinati, tabelle con migliaia di righe in cui bisogna strofinare il dito sulla rotellina del mouse per vedere il titolo, tonnellate di pagine di istruzioni non numerate, centinaia di email inoltrate l'una all'altra con dati da analizzare e sistematizzare e inserire in altrettante tabelle illeggibili.

E così, quando mi sono un po' calmata, ho deciso di scrivere questo articolo. Parlerò di come gestire normalmente (a volte anche in modo comodo) la documentazione non di prodotto. Spero che l'articolo venga condiviso in rete e che il livello di caos nei vari reparti che lavorano a contatto con lo sviluppo diminuisca almeno un pochino, e che le persone (compresa me) diventino un po' più felici.

Strumenti

La documentazione di prodotto è spesso archiviata vicino al codice, e questo è positivo. La documentazione non di prodotto, invece, di solito viene conservata in modo casuale. Spesso le persone cercano di trasferire informazioni da diversi luoghi in Confluence, e noi non facciamo eccezione. Quindi, tutto il resto del racconto parlerà di questo.

In generale, Confluence è un avanzato motore wiki. Permette di lavorare con dati in varie forme di visualizzazione: testo formattato, tabelle, vari grafici. È uno strumento molto interessante e potente, ma se non sai come prepararlo, otterrai solo un'altra discarica di documenti illeggibili. Ti insegnerò a prepararlo!

Macro

Quasi tutta la magia di Confluence si basa sulle macro. Ce ne sono molte, e possono essere combinate tra loro. Alcune sono a pagamento e altre gratuite; ci saranno vari esempi di macro con link alla documentazione per ciascuna di esse.

L'interfaccia per lavorare con le macro è estremamente semplice. Per aggiungere una macro, basta cliccare sul segno più e selezionare l'elemento desiderato dall'elenco.

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

Se per il funzionamento del macro è necessario inserire qualcosa al suo interno, appare come una cornice.

Allo stesso modo, è possibile inserire quante più cornici si desidera, purché ci sia logica nella vostra piramide.

Ogni macro ha un'anteprima: qui si può vedere subito se il macro è stato compilato e configurato correttamente.

Modelli

Oltre ai macro, esiste uno strumento comodo per il precompilamento dei contenuti: è il modello.
I modelli possono essere utilizzati nella creazione di qualsiasi pagina: basta fare clic sui tre punti accanto al pulsante 'Crea' e selezionare il modello desiderato.

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

Chiunque può creare pagine da modelli, ma solo chi ha i diritti può creare o modificare i modelli stessi. È possibile aggiungere istruzioni aggiuntive all'interno del modello su come gestire la pagina.

La magia delle tabelle

In realtà, come tecnico, amo teneramente le tabelle e posso quasi racchiudere qualsiasi informazione in esse (anche se non sempre è efficace). Le tabelle sono chiare, strutturate, scalabili, magiche!

Ma anche una meravigliosa entità come la tabella può essere rovinata. Al contrario, può essere utilizzata con successo e persino migliorata. Di questo parleremo 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. Per questo si può utilizzare un macro a pagamento. ‘Filtro tabelle’.

All'interno di questo macro bisogna inserire la tabella (può anche essere la più brutta, l'importante è inserirla per intero). All'interno del macro è possibile selezionare colonne per il filtro da un elenco a discesa, un filtro testuale, numerico e un filtro per date.

Immaginate di registrare tutte le informazioni sui candidati per tutte le posizioni in un elenco tabellare. Naturalmente, non è ordinato - le persone non si presentano ai colloqui in ordine alfabetico. E voi dovete capire se avete già fatto un colloquio con un determinato candidato. Basta inserire questo caos nel macro di filtraggio, aggiungere un filtro testuale per il cognome - ed ecco, l'informazione è sullo schermo.

Va notato che la filtrazione di enormi tabelle può influenzare le prestazioni del sistema e il tempo di caricamento delle pagine, quindi infilare un'enorme tabella in un filtro è una soluzione temporanea; è meglio strutturare il processo in modo che le persone non debbano creare tabelle enormi e illeggibili (un esempio di processo sarà alla fine dell'articolo).

Ordinamento (plugin a pagamento)

Con il magico macro ‘Filtro tabelle’ è possibile anche impostare l'ordinamento predefinito su qualsiasi colonna e numerare le righe. Oppure, cliccando su qualsiasi colonna della tabella infilata nel macro filtro, si effettuerà l'ordinamento su quella colonna.

Ad esempio, avete la stessa tabella con i candidati e volete calcolare quante interviste sono state svolte in un determinato mese: ordinate per data e godetevi il risultato.

Tabelle pivot (plugin a pagamento)

Ora passiamo a un caso più interessante. Immaginate che la vostra tabella sia enorme e dobbiate fare dei calcoli su di essa. Certo, si può copiare in Excel, fare i calcoli necessari e caricare nuovamente i dati in Confluence. Oppure si può applicare una volta il macro "Tabella pivot" e ottenere lo stesso risultato, ma con la funzione di aggiornamento.

Ad esempio: avete una tabella che raccoglie i dati di tutti i dipendenti — dove si trovano e quali ruoli ricoprono. Per contare quante persone ci sono in ogni città, dovete selezionare nel macro "Tabella pivot" la riga per cui aggregare i dati (posizione) e il tipo di operazione (somma).

Naturalmente, è possibile raggruppare per più criteri contemporaneamente; tutte le possibilità possono essere visionate nella documentazione.

Grafici (plugin a pagamento)

Come ho già detto, non tutti amano le tabelle tanto quanto me. Sfortunatamente, i manager, per la maggior parte, non le amano affatto. Tuttavia, tutti adorano i grafici colorati e vivaci.
I creatori di Confluence ne erano sicuramente consapevoli (sicuramente hanno anche un dirigente che ama i report e i grafici, che ci vuoi fare). Pertanto, è possibile utilizzare il magico macro "Grafico da tabella". In questo macro dovete inserire la tabella pivot del punto precedente e voilà — i vostri dati grigi e noiosi sono bellamente visualizzati.

Naturalmente, questo macro ha anche delle impostazioni. Il link alla documentazione per qualsiasi macro può essere trovato in modalità di editing di questa macro.

Semplicità di aggregazione

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

Tag

È un problema quando le persone conservano informazioni in un'unica grande voce disorganizzata o in un'enorme tabella. Ancora peggio è quando parti di queste informazioni non sono solo poco leggibili, ma sono anche sparse in giro su Confluence. Fortunatamente, esiste la possibilità di raccogliere queste informazioni in un unico luogo. Per questo motivo, è necessario utilizzare etichetta (note a tutti per i tag dei social media).

Su ogni pagina è possibile aggiungere qualsiasi numero di etichette. Se cliccate su un'etichetta, verrete portati a una pagina di aggregazione, dove sono presenti collegamenti a tutti i materiali con quell'etichetta, nonché a un insieme di etichette correlate. Le etichette correlate sono quelle che si trovano frequentemente sulla stessa pagina.

Proprietà della pagina

È possibile aggiungere un altro interessante macro alla pagina per strutturare le informazioni — «Proprietà della pagina». All'interno di esso, è necessario fornire una tabella di due colonne, la prima sarà la chiave e la seconda il valore della proprietà. Inoltre, è possibile nascondere il macro dalla pagina, in modo che non distragga dalla lettura del contenuto, ma la pagina sarà comunque contrassegnata con le chiavi necessarie.

Fate attenzione all'ID — è utile impostarlo per applicare diversi gruppi di proprietà su pagine diverse (o anche diversi gruppi di proprietà sulla stessa pagina).

Rapporti

È possibile raccogliere report tramite le etichette. Ad esempio, il macro «Rapporto sui contenuti» raccoglie tutte le pagine con un determinato insieme di etichette.

Ma il rapporto più interessante è il macro «Rapporto sulle proprietà della pagina». Anche questo raccoglie tutte le pagine con un determinato insieme di etichette, ma non si limita a fornire un elenco; compila una tabella (capite il collegamento con l'inizio dell'articolo?), i cui colonne sono le chiavi delle proprietà della pagina.

Si ottiene quindi una tabella pivot delle informazioni provenienti da diverse fonti. È piacevole che abbia funzionalità convenienti: layout reattivo, ordinamento per qualsiasi colonna. Inoltre, è possibile configurare una tabella di report all'interno del macro.

In fase di configurazione è possibile rimuovere alcune colonne dal report, impostare uno stato predefinito o il numero di iscrizioni visualizzate. Inoltre, è possibile impostare l'ID della proprietà della pagina per visualizzare solo le informazioni necessarie.

Ad esempio, hai molte pagine di dipendenti, e ciascuna di queste pagine ha un insieme di proprietà riguardanti la persona: a quale livello si trova, dove si trova, 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 la persona, in quale team si trova e così via. Queste proprietà sono contrassegnate ID = team_inf. Quindi, durante la creazione di un rapporto, puoi estrarre solo informazioni relative a un unico ID o a entrambi — come preferisci.

Il bello di questo approccio è che ciascuno può creare la tabella informativa di cui ha bisogno, che non duplicherà nulla e si aggiornerà quando viene aggiornata la pagina principale. Ad esempio: al team leader non interessa quando i suoi sviluppatori sono stati assunti, ma è importante sapere quale ruolo ciascuno di loro svolge nel team. Il team leader raccoglierà il report sul team. E al contabile non importa chi svolge quale ruolo, ma le posizioni sono importanti — raccoglierà il report sulle posizioni. In questo modo, la fonte delle informazioni non verrà duplicata o trasferita.

Processo finale

Istruzioni

Quindi, possiamo strutturare in modo elegante ed aggregare in modo efficace le informazioni in Confluence utilizzando i macros. Ma in ideale, dovrebbe essere fatto in modo che le nuove informazioni siano immediatamente strutturate e rientrino in tutti i meccanismi di aggregazione già utilizzati.

Qui entra in gioco la combinazione di macros e template. Per incoraggiare le persone a creare nuove pagine nel formato corretto, puoi utilizzare il macro "Crea da modello". Questo aggiunge un pulsante alla pagina, cliccando sul quale viene creata una nuova pagina dal template necessario. In questo modo costringi le persone a lavorare sin dall'inizio nel formato che desideri.

Nel template da cui si permette di creare la pagina, è necessario aggiungere in anticipo i tag, il macro "Proprietà della pagina" e la tabella delle proprietà necessarie. Consiglio anche di aggiungere istruzioni su quali valori devono essere inseriti nella pagina e sui valori delle proprietà.

Quindi il processo finale apparirà così:

Crei un template per informazioni di un certo tipo.
In questo template aggiungi tag e proprietà della pagina nel macro.
In qualsiasi luogo conveniente, crei una pagina principale con un pulsante, cliccando sul quale viene creata una pagina secondaria da un modello.
Permetti agli utenti di accedere alla pagina principale, che potrebbero generare le informazioni necessarie (secondo il modello richiesto, cliccando sul pulsante).
Raccogli un report sugli attributi della pagina tramite i tag che hai specificato nel modello.
Ti rallegra: hai tutte le informazioni necessarie in un formato comodo.

Inconvenienti

In qualità di ingegnere della qualità, posso affermare con certezza che nulla di perfetto esiste al mondo. Anche le tabelle divine non sono perfette. Ci sono delle insidie nel processo sopra descritto.

Se decidi di cambiare i nomi o la composizione degli attributi della pagina, dovrai aggiornare tutti gli oggetti già creati affinché i loro dati vengano correttamente incorporati nel report aggregato. Questo è triste, ma d'altra parte, costringe a pensare attentamente all'«architettura» del tuo insieme di informazioni, che è un compito molto interessante.
Dovrai scrivere una quantità considerevole di istruzioni su come compilare le tabelle informative e utilizzare i tag. Ma, d'altra parte, puoi semplicemente condividere questo articolo con tutte le persone necessarie.

Esempio di archiviazione di documentazione non di prodotto

Attraverso il processo descritto sopra, puoi organizzare l'archiviazione di quasi qualsiasi informazione. La bellezza dell'approccio è che è universale: quando gli utenti si abitueranno, smetteranno di generare confusione. Inoltre, un grande (ma non gratuito) vantaggio è la possibilità di raccogliere statistiche varie al volo e creare grafici esteticamente gradevoli.

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 secondo il quale ogni nuovo membro crea la propria scheda e annota tutte le informazioni personali.

Come puoi vedere, abbiamo una tabella dettagliata di attributi e ci sono istruzioni su come gestire correttamente questa pagina. Parte dei tag sono impostati dagli stessi dipendenti secondo le istruzioni, nel modello ci sono solo i principali: il tag della scheda employee-card, il tag della direzione direction-involve e il 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 creare tabelle generali, mentre i leader dei team possono creare tabelle di team, aggiungendo il tag del team nella selezione.

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