Documentația nu ar trebui să fie o corvoadă. Ar trebui să fie un rezultat al muncii
În multe organizații, documentația este tratată ca o activitate care poate fi făcută „după ce terminăm treaba”. În practică, acel „după” nu mai vine aproape niciodată. Iar atunci când oamenii pleacă din echipă, pleacă și o parte importantă din cunoștințele care ține proiectele în mișcare.
Raționamentul din spatele unei decizii, contextul unui task, definiția criteriilor de finalizare sau motivul pentru care o anumită soluție a fost aleasă rămân adesea în mintea oamenilor, în conversații de chat sau în întâlniri. Problema devine evidentă abia când persoanele respective nu mai sunt disponibile.
Aceasta a fost ideea centrală a sesiunii susținute de Monika Ambrozowicz la Work Evolution Summit: un sistem de documentare eficient nu ar trebui să depindă de disciplina oamenilor de a scrie documentație suplimentară. Ideal, documentația ar trebui să fie un produs secundar al modului în care echipa lucrează.
Când un proiect moștenește doar un board Jira
Un exemplu cât se poate de concret. Un product owner a preluat recent un proiect important, dedicat mentenanței unei aplicații disponibile în Atlassian Marketplace. A primit și board-ul Jira care ar fi trebuit să îi ofere imaginea de ansamblu asupra proiectului.
În locul unei hărți clare a activității, a găsit însă un board plin de ticket-uri goale sau aproape goale. Unele descrieri se rezumau la formulări precum „așa cum am discutat pe Slack”.
Echipa anterioară își făcuse foarte bine treaba. Problema era că membrii echipei știau totul, iar informația exista aproape exclusiv în memoria lor.
Când au plecat, contextul a dispărut.
Noua echipă a trebuit să ghicească ce fusese decis, să contacteze foști membri ai proiectului și, în unele cazuri, să refacă activități care fuseseră deja realizate.
Aceasta este exact problema care trebuie rezolvată înainte de a vorbi despre automatizarea documentației.
Nu poți construi un sistem care se documentează singur pornind de la ticket-uri care nu conțin informațiile necesare. Mai întâi trebuie corectat inputul. Apoi poate fi automatizat output-ul.
„Hope is not a strategy”
Problema inputului apare în mai multe forme, dar toate au aceeași cauză.
Prima este reprezentată de proiectele moștenite. Oamenii nu sunt întotdeauna consecvenți în modul în care creează și întrețin ticket-urile. Unii sunt foarte disciplinați, alții scriu minimum necesar, iar alții presupun că informația se află deja într-o conversație pe Slack.
Responsabilii de Jira – Scrum Masteri, team lead-uri, dezvoltatori sau administratori – ajung astfel să spere că ceilalți vor respecta procesul.
Dar „hope is not a strategy”. Și nici nu poate fi fundația unui sistem.
A doua problemă este volumul. În anumite organizații, același tip de activitate trebuie repetat de zeci sau chiar sute de ori. Un exemplu prezentat în cadrul sesiunii a fost cel al unui product owner din retail care poate ajunge să creeze până la 200 de work item-uri de fiecare dată când compania deschide un magazin nou.
Repetarea manuală nu aduce valoare, dar introduce erori și consumă timp.
A treia situație este raportarea bug-urilor de către persoane non-tehnice. Un raport de tipul „vreau să fie reparat imediat” nu îi oferă dezvoltatorului informațiile de care are nevoie: pașii pentru reproducerea problemei, mediul în care a apărut sau utilizatorii afectați.
De cele mai multe ori, problema nu este lipsa de bunăvoință. Persoana care raportează pur și simplu nu știe ce informații sunt relevante.
Soluția este să îi oferi ghidaj chiar în momentul în care creează ticket-ul.
Primul pas: template-uri pentru un input de calitate
Un sistem care se documentează singur începe, așadar, cu template-uri.
Jira nu oferă nativ toate capabilitățile necesare pentru acest tip de abordare, motiv pentru care ecosistemul Atlassian Marketplace poate completa aceste funcții prin aplicații specializate.
În demonstrația Monikăi a fost prezentată Templating App de la Siebert Products, o soluție pentru standardizarea modului în care sunt create și descrise work item-urile.
Un rol important îl au description templates. În locul unui câmp gol care îl lasă pe utilizator să decidă singur ce trebuie să scrie, template-ul oferă structura necesară.
De exemplu, atunci când un work item este transformat într-un bug, poate apărea automat un model de descriere care îi cere utilizatorului informații precum:
• pașii pentru reproducerea problemei;
• comportamentul așteptat;
• comportamentul observat;
• mediul afectat;
• informații despre utilizatorii impactați.
Utilizatorul rămâne liber să modifice conținutul, dar nu mai pornește de la o pagină goală.
Același principiu poate fi aplicat și regulilor de rutare. În funcție de tipul solicitării sau de anumite câmpuri, ticket-ul poate ajunge automat într-un anumit status sau într-o anumită zonă a fluxului.
Când trebuie create 100 de ticket-uri, automatizarea devine esențială
Issue templates duc conceptul mai departe. Ele permit generarea unui număr mare de work item-uri care respectă aceeași structură.
Un element important este utilizarea variabilelor.
Dacă trebuie create 100 de ticket-uri care includ numele unei aplicații în titlu, nu este nevoie ca acel nume să fie introdus manual de 100 de ori. Variabila este definită o singură dată și completată automat pentru fiecare element.
Același principiu poate fi utilizat pentru roluri, responsabilități, subtasks și alte elemente repetitive.
Rezultatul este un set de work item-uri create în câteva secunde, cu variabilele completate și cu structura deja pregătită.
Întrebarea relevantă pentru orice echipă este simplă: câte ore sunt consumate în prezent pentru astfel de activități repetitive și ce valoare adaugă, de fapt, munca manuală?
De la ticket la documentație, fără muncă suplimentară
Odată ce ticket-urile sunt bine structurate și conțin informațiile necesare, apare următorul pas logic: transformarea lor automată în documentație.
Aici intervine o altă problemă organizațională: nu toți cei care trebuie să cunoască statusul unui proiect lucrează în Jira.
Dezvoltatorii și echipele tehnice se simt confortabil în Jira. Pentru un specialist în vânzări, un product marketer sau un manager, însă, accesarea unui board Jira poate fi mai puțin naturală.
Un vanzator trebuie să știe dacă o funcționalitate promisă unui client este gata. Marketingul trebuie să urmărească stadiul unei lansări. Managementul are nevoie de informații actualizate înaintea unei ședințe.
Nu este realist să presupui că toți acești oameni vor intra zilnic în Jira.
În multe organizații, locul natural pentru această categorie de informații este Confluence.
De aici vine următoarea etapă a sistemului: sincronizarea dintre Jira și Confluence.
Autopage: documentația care rămâne sincronizată
În cadrul sesiunii a fost demonstrată soluția Autopage, care transformă automat work item-urile Jira în pagini Confluence și, esențial, menține cele două surse sincronizate.
Diferența este importantă.
Dacă un ticket este redeschis, se schimbă termenul-limită sau este modificată persoana responsabilă, pagina Confluence se actualizează automat.
În demonstrație, un bug creat cu ajutorul unui description template a fost publicat ca pagină Confluence, câmpurile Jira fiind mapate prin macro-uri Autopage.
Inclusiv work item-urile asociate și subtasks pot fi reflectate în structură. Astfel, un epic poate deveni pagina principală, iar stories și subtasks pot fi reprezentate ca subpagini conectate.
Regula de automatizare este configurată o singură dată. Ulterior, atunci când ticket-ul este creat sau actualizat, pagina corespunzătoare este creată sau actualizată automat.
De ce sincronizarea este mai importantă decât simpla creare a unei pagini
În sesiunea de întrebări și răspunsuri, una dintre întrebări a vizat diferența dintre această abordare și funcționalitățile native Atlassian, inclusiv Jira Automation și Rovo.
Răspunsul evidențiază o diferență esențială: crearea unei pagini nu este același lucru cu menținerea ei sincronizată.
O automatizare poate crea o pagină Confluence pe baza unui ticket, însă fără un mecanism de sincronizare, pagina poate deveni rapid o fotografie a unei situații care nu mai există.
Ticket-ul se modifică. Statusul se schimbă. Termenul este amânat. Responsabilul este înlocuit.
Pagina rămâne însă neschimbată.
În cazul Rovo, utilizatorul poate solicita generarea sau actualizarea informațiilor, însă trebuie să inițieze procesul și să verifice rezultatul.
Abordarea Autopage prezentată în cadrul sesiunii pornește de la o regulă configurată o singură dată și urmărește permanent modificările din Jira.
Avantajul este tocmai sincronizarea în timp real.
O singură sursă de adevăr, mai multe puncte de acces
La prima vedere, păstrarea informațiilor atât în Jira, cât și în Confluence poate părea redundantă.
De ce să avem aceleași date în două locuri?
Răspunsul ține mai puțin de tehnologie și mai mult de modul în care funcționează organizațiile.
Jira poate rămâne sursa de adevăr pentru echipa tehnică, în timp ce Confluence devine interfața prin care informația este accesibilă celorlalți.
Un manager nu trebuie să învețe structura unui board complex pentru a afla statusul unui proiect. Un specialist în marketing nu trebuie să urmărească fiecare ticket. Un coleg din vânzări nu trebuie să ceară de fiecare dată unui dezvoltator o actualizare.
Informația ajunge în locul în care acești utilizatori o caută deja.
Mai important, nu mai depinde de o pagină creată manual și abandonată ulterior.
Jira rămâne sursa de adevăr, iar Confluence devine o reprezentare actualizată a acesteia.
Documentația ca efect secundar al muncii
Puse cap la cap, cele două componente rezolvă două probleme diferite.
Template-urile îmbunătățesc calitatea informației introduse în Jira și elimină o parte din activitățile repetitive.
Automatizarea Jira–Confluence transformă acea informație într-o formă accesibilă și pentru utilizatorii care nu lucrează direct în Jira, menținând-o actualizată.
Rezultatul este mai mult decât o colecție de instrumente. Este o schimbare de proces.
În loc să le ceri oamenilor să scrie documentația după ce termină munca, proiectezi fluxul astfel încât informația relevantă să fie colectată în timp ce munca este făcută.
În acest model, documentația nu mai este o sarcină suplimentară care poate fi amânată. Devine un by-product al procesului de lucru.
Iar acesta este, probabil, cel mai important mesaj al sesiunii: nu trebuie să speri că echipa va documenta mai bine. Trebuie să construiești un sistem în care documentarea corectă să fie comportamentul implicit.
Pentru organizațiile care folosesc Jira și Confluence, aceasta poate fi diferența dintre un proiect în care informația dispare odată cu oamenii și unul în care cunoștințele rămân disponibile, actualizate și ușor de găsit.
Întrebarea pentru orice echipă este, prin urmare, simplă: unde se află astăzi cunoștințele critice ale organizației – în sistemele voastre sau încă în capul oamenilor?
de Monika Ambrozowicz, product marketing manager la Siebert Products
