🥇Proiectare în Confluence

Salut tuturor!

Numele meu este Masha, lucrez ca inginer QA în grupul de companii Tinkoff. Activitatea în QA implică multe comunicații cu diferite persoane din echipe diverse, iar eu am fost și manager și lector pentru programe educaționale, astfel că harta mea de comunicații a fost extrem de extinsă. Și într-un anumit moment, am explodat: am realizat că nu mai pot, nu mai pot, nu mai pot umple tone de tabele și documente ilegibile.

Cu siguranță, fiecare dintre voi și-a imaginat acum despre ce vorbesc, și a tras o săgeată rece: liste de nume fără o ordine alfabetică, tabele cu sute de coloane cu formatare strâmbă, tabele cu mii de rânduri în care trebuie să îți freci degetul pe rotița mouse-ului pentru a vedea titlul, tone de pagini de instrucțiuni nepăstrate în ordine, sute de e-mailuri trimise unii altora cu date care trebuie analizate și sistematizate și înghesuite în tabele la fel de ilegibile.

Și iată că, după ce m-am mai calmat, am decis să scriu acest articol. Voi vorbi despre cum putem gestiona în mod corect (chiar uneori confortabil) documentația non-produs. Sper că articolul se va răspândi pe rețea și nivelul haosului din departamentele din jurul dezvoltării va scădea puțin, iar oamenii (inclusiv eu) vor deveni puțin mai fericiți.

Instrumente

Documentația de produs este adesea păstrată alături de cod, ceea ce este bine. În schimb, documentația non-produs este de obicei stocată în locuri diverse. Adesea, oamenii încearcă să transfere informații din diferite locații în Confluence, iar noi nu suntem o excepție. Așadar, toată povestea de mai departe este despre acesta.

În general, Confluence este un motor wiki avansat. Permite lucrul cu date în diferite forme de afișare: text formatat, tabele, diverse diagrame. Este un instrument foarte interesant și puternic, dar dacă nu știi cum să-l configurezi, vei obține o nouă grămadă de documente ilegibile. Te voi învăța cum să-l configurezi!

Macrosuri

Aproape toată magia Confluence se bazează pe macrosuri. Există foarte multe macrosuri și le poți combina între ele. Acestea pot fi plătite sau gratuite, urmează diferite exemple de macrosuri cu linkuri către documentația lor.

Interfața de lucru cu macrosurile este extrem de simplă. Pentru a adăuga un macros, trebuie să dai clic pe plus și să alegi elementul dorit din listă.

Dacă un macro este autosuficient, adică nu necesită inserarea altceva în interior, acesta arată ca un bloc.

Dacă pentru funcționarea macro-ului este nevoie să se pună ceva în interiorul acestuia, el se prezintă ca un cadru.

În interiorul unui cadru se pot încadra oricâte alte cadre, atâta timp cât logică există în piramida voastră.

Fiecare macro are o previzualizare: din aceasta se vede imediat dacă ați completat și configurat corect macro-ul.

Șabloane

Pe lângă macro-uri, există un instrument util de completare automată a conținutului - acesta este șablonul.
Șabloanele pot fi utilizate la crearea oricărei pagini: trebuie doar să faceți clic pe cele trei puncte de lângă butonul „Creează” și să alegeți șablonul dorit.

Atunci, întreaga conținut pe care îl are șablonul va fi adăugat pe pagina creată.

Oricine poate crea pagini din șabloane, dar doar cei care au permisiuni pot crea sau edita șabloanele în sine. Într-un șablon pot fi adăugate instrucțiuni suplimentare despre cum ar trebui să fie gestionată pagina.

Magia tabelelor

De fapt, ca specialist tehnic, îmi iubesc cu sinceritate tabelele și pot transforma aproape orice informație în ele (deși nu este întotdeauna eficient). Tabelele în sine sunt clare, structurate, scalabile, magice!

Dar chiar și o entitate remarcabilă, cum este tabela, poate fi stricat. Dar poate fi utilizată cu succes și chiar îmbunătățită. Despre asta mai jos.

Filtrare (plugin plătit)

Orice tabel uriaș și ilizibil poate fi făcut puțin mai puțin uriaș și puțin mai lizibil prin filtrare. Pentru aceasta, poate fi utilizat un macro plătit. „Filtru tabele”.

În interiorul acestui macro trebuie să introduci tabela (poate chiar cea mai urâtă, important e să o incluzi complet). În macro pot fi selectate coloanele pentru filtrare dintr-o listă derulantă, filtrul text, numeric și filtrul de date.

Imaginați-vă că toată informația referitoare la candidați pentru toate posturile disponibile este înregistrată sub formă de listă tabelară. Evident, aceasta nu este sortată - oamenii vin la interviuri nu în ordine alfabetică. Iar voi trebuie să înțelegeți dacă ați avut un interviu cu un anumit candidat anterior. Tot ce trebuie să faceți este să introduceți acest haos în macro-ul de filtrare, să adăugați un filtru text pe nume și voila, informația este pe ecranul vostru.

Este important de remarcat faptul că filtrarea tabelelor mari poate afecta funcționarea sistemului și timpul de încărcare a paginilor. Prin urmare, a crea un tabel imens cu filtru este o soluție temporară; ar fi mai bine să concepeți un proces în care utilizatorii să nu fie nevoiți să creeze tabele mari și greu de citit (un exemplu de proces va fi la finalul articolului).

Sortare (plugin plătit)

Prin intermediul macro-ului magic „Filtru tabele” se poate, de asemenea, stabili o sortare implicită pentru orice coloană și numerota rândurile. Sau se poate face clic pe orice coloană a tabelului inclus în macro-ul filtrului, iar acesta va fi sortat după această coloană.

De exemplu, aveți același tabel cu candidați și trebuie să estimați câte interviuri au avut loc într-o anumită lună — sortati după dată și bucurați-vă.

Tabele pivotante (plugin plătit)

Acum să trecem la un caz mai interesant. Imaginează-ți că tabelul tău este imens și trebuie să calculezi ceva pe baza lui. Desigur, poți să-l copiezi în Excel, să faci calculele necesare și să imporți datele înapoi în Confluence. Sau poți aplica o dată macro-ul „Tabel pivotant” și să obții același rezultat, doar că acesta va fi și actualizat.

De exemplu: ai un tabel care adună datele tuturor angajaților — unde se află geografic și ce funcții ocupă. Pentru a număra câți oameni sunt în fiecare oraș, trebuie să selectezi în macro-ul „Tabel pivotant” rândul pe care se agregă datele (locația) și tipul de operațiune (adunare).

Desigur, se pot grupa după mai multe criterii simultan, toate posibilitățile pot fi consultate în documentație.

Diagramă (plugin plătit)

Așa cum am menționat, nu toată lumea iubește tabelele la fel de mult ca mine. Din păcate, managerii, în majoritatea lor, nu le plac deloc. Cu toate acestea, toată lumea iubește diagramele colorate și vibrante.
Creatorii Confluence, fără îndoială, erau conștienți de acest lucru (din păcate, și ei au șefi care iubesc rapoartele și diagramele, nu-i așa?). Prin urmare, poți utiliza macro-ul magic „Diagramă din tabel”. Acest macro necesită să pui tabelul pivotant din punctul anterior și, voilà — datele tale plictisitoare și gri sunt frumos vizualizate.

Desigur, acest macro are și setări. Legătura către documentația oricărui macro poate fi găsită în modul de editare al acestuia.

Simplitatea agregării

Informațiile din punctele anterioare nu v-au fost cu siguranță o noutate. Dar acum știți cu siguranță să folosiți macrocomenzi, iar eu pot trece la partea mai interesantă a articolului.

Etichete

Este neplăcut când oamenii păstrează informațiile într-un singur articol nestrukturat sau într-un tabel imens. Și mai rău este când părți din aceste informații sunt nu doar greu de citit, ci și împrăștiate prin Confluence. Din fericire, există posibilitatea de a strânge informațiile împrăștiate la un loc. Pentru aceasta, trebuie să folosiți etichetele (cunoscute tuturor din rețelele sociale).

Pe orice pagină se pot adăuga un număr nelimitat de etichete. Dacă dați clic pe o etichetă, veți ajunge pe o pagină de agregare, unde sunt linkuri către toate materialele cu acea etichetă, precum și cu un set de etichete înrudite. Etichetele înrudite sunt cele care apar frecvent pe aceeași pagină.

Proprietățile paginilor

Pe pagină se poate adăuga un alt macrocomandă interesant pentru structurarea informațiilor — „Proprietățile paginilor”. În interiorul său trebuie să introduceți un tabel cu două coloane, prima fiind cheia, iar a doua — valoarea proprietății. De asemenea, macrocomanda poate fi ascunsă de pe pagină, astfel încât să nu perturbe lectura conținutului, dar pagina va fi totuși marcată cu cheile necesare.

Atenție la ID — este convenabil să-l setați pentru a asocia diferite grupuri de proprietăți pe pagini diferite (sau chiar diferite grupuri de proprietăți pe aceeași pagină).

Rapoarte

Pe baza etichetelor se pot genera rapoarte. De exemplu, macrocomanda „Raport despre conținut” strânge toate paginile cu un set specific de etichete.

Dar un raport mai interesant este macrocomanda „Raport despre proprietățile paginii”. Acesta strânge de asemenea toate paginile cu un set specific de etichete, dar nu doar le listează, ci creează un tabel (observați legătura cu începutul articolului?), în care coloanele reprezintă cheile proprietăților paginii.

Rezultatul este un tabel de sumar cu informații din diferite surse. Este plăcut că are funcții convenabile: design adaptabil, sortare pe orice coloană. De asemenea, acest tabel de raport poate fi configurat în cadrul macrocomenzii.

Când faceți configurația, puteți elimina anumite coloane din raport, stabili un stări implicită sau un număr de înregistrări afișate. De asemenea, puteți defini ID-ul proprietății paginii pentru a vedea doar informațiile necesare.

De exemplu, aveți mai multe pagini ale angajaților, iar aceste pagini au un set de proprietăți despre persoană: ce nivel are, unde se află, când a venit în echipă și așa mai departe. Aceste proprietăți sunt marcate ID = employee_inf. Și există un al doilea set de proprietăți pe aceeași pagină, în care este adunată informația despre persoană, ca parte a echipei: ce rol are persoana, în ce echipă se află și așa mai departe. Aceste proprietăți sunt marcate ID = team_inf. Astfel, la generarea raportului, puteți extrage informațiile pe baza unui singur ID sau simultan pentru ambele - așa cum este mai convenabil.

Frumusețea acestui mod de abordare constă în faptul că oricine poate crea tabela de informații de care are nevoie, care nu va dubla nimic și se va actualiza la fiecare actualizare a paginii principale. De exemplu: liderul de echipă nu îi pasă când și-au început lucrul dezvoltatorii săi, dar este important ce rol joacă fiecare dintre ei în echipă. Liderul de echipă va crea un raport pentru echipă. Iar contabilului nu îi pasă cine ce rol are, dar este importantă funcția - el va crea un raport pe funcții. Astfel, sursa de informație nu va fi duplicată sau mutată.

Procesul final

Instrucțiune

Așadar, putem structura frumos și eficient informația în Confluence pe exemplul utilizării macro-urilor. Dar în ideal, ar trebui să facem astfel încât noile informații să fie imediat structurate și să ajungă în toate mecanismele de agregare deja folosite.

Aici vine în ajutor combinația de macro-uri și șabloane. Pentru a determina oamenii să creeze pagini noi în formatul dorit, puteți utiliza macro-ul „Creează din șablon”. Acesta adaugă pe pagină un buton, apăsând pe care se creează o pagină nouă din șablonul dorit. Astfel, îi determinați pe oameni să lucreze imediat în formatul dorit.

În șablonul din care permiteți crearea paginii, trebuie să adăugați din timp etichete, macro-ul „Proprietăți ale paginii” și tabelul cu proprietățile dorite. De asemenea, recomand să adăugați instrucțiuni despre ce valori ar trebui să completeze în pagină și valorile proprietăților.

Atunci, procesul final va arăta astfel:

Creezi un șablon pentru informații de un anumit tip.
În acest șablon adăugați etichete și proprietățile paginii în macro.
În orice loc convenabil, creați o pagină rădăcină cu un buton, la click-ul căruia se va crea o pagină fiică dintr-un șablon.
Permiteți utilizatorilor să acceseze pagina rădăcină, care pot genera informațiile necesare (după șablonul dorit, apăsând pe buton).
Adunați un raport pentru proprietățile paginii prin etichetele pe care le-ați specificat în șablon.
Vă bucurați: aveți toate informațiile necesare într-un format convenabil.

Capcane

Ca inginer de calitate, pot afirma cu încredere că nu există nimic perfect în lume. Chiar și tabele divine sunt imperfecte. Și în procesul menționat mai sus, există capcane.

Dacă decideți să schimbați numele sau compunerea proprietăților paginii, va trebui să actualizați toate obiectele deja create, astfel încât datele lor să fie corect afișate în raportul central. E trist, dar, pe de altă parte, vă obligă să gândiți detaliat arhitectura setului dvs. de informații, ceea ce reprezintă o sarcină foarte interesantă.
Va trebui să scrieți un număr considerabil de instrucțiuni despre cum să completați tabelele informaționale și să utilizați etichetele. Dar, pe de altă parte, puteți pur și simplu să trimiteți această articolă tuturor persoanelor necesare.

Exemplu de stocare a documentației non-producție

Prin procesul descris mai sus, puteți organiza stocarea aproape oricăror informații. Frumusețea acestui abord este că este universal: odată ce utilizatorii se obișnuiesc cu el, încetează să mai genereze haos. De asemenea, un mare (dar nu gratuit) avantaj este posibilitatea de a colecta diverse statistici în timp real și de a crea diagrame frumoase pe baza acestora.

Vă voi da un exemplu al procesului nostru de gestionare a informațiilor despre echipă.

Pentru fiecare persoană din echipă, am decis să creăm un dosar al angajatului. În consecință, avem un șablon conform căruia fiecare nouă persoană își creează acest dosar și își gestionează informațiile personale.

După cum puteți vedea, avem un tabel extins de proprietăți și sunt deja instrucțiuni despre cum să gestionați această pagină. O parte din etichete sunt completate de angajați conform instrucțiunilor, în șablon există doar cele principale: eticheta dosarului employee-card, eticheta direcției direction-involve și eticheta echipei team-qa.

În cele din urmă, după ce fiecare și-a creat propria cartela, se obține un tabel complet cu informații despre angajați. Aceste informații pot fi utilizate în diferite puncte. Managerii de resurse pot crea tabele comune, iar liderii echipelor — tabele de echipă, adăugând în selecție eticheta echipei.

După etichete, se pot vedea diferite sinteze, de exemplu, pentru qa-upgrade-plan vor fi afișate toate sarcinile de dezvoltare QA. Fiecare persoană din cartela sa de angajat ține o poveste importantă și propriul său plan de dezvoltare — creează o pagină încorporată din șablonul planurilor de dezvoltare.