Soluțiile software, echipamentele industriale, instrumentele medicale, produsele electrocasnice (și nu numai) presupun nu doar crearea și/sau livrarea produsului în sine, ci și furnizarea/oferirea unei documentații suport (de exemplu, a unui manual de instrucțiuni) pentru clienții sau utilizatorii finali. În spatele documentației se află de cele mai multe ori un Technical Writer.
În cadrul acestui articol ne propunem să prezentăm ce presupune această meserie. În această primă parte a articolului, vom vorbi despre activitățile și provocările unui Technical Writer. În a doua parte a articolului (într-un număr viitor) vom analiza tehnicile și instrumentele pe care le folosește un Technical Writer.
Struțo-cămila, furculicion-ul sau "technical writer"-ul sunt câteva specimene hibride, mai noi și mai vechi.
Profesia de technical writer a apărut în urmă cu aproximativ un secol, potrivit Society for Technical Communication (STC) în contextul Primului Război Mondial. Cu toate acestea, denumirea profesiei ca atare s-a încetățenit în clasificările oficiale, doar în ultimele două decenii.
Technical Writerul este un comunicator profesionist de informații, care transferă, mediază (e un intercesor), "traduce" informația primită de la specialiștii din diverse domenii (programatori, ingineri, proiectanți), facilitând înțelegerea acesteia de către publicul larg. Rezultatul este o informație relevantă, utilă și clară, adaptată publicului-țintă.
Dacă ați citit sau răsfoit vreodată un set de instrucțiuni, o procedură, un raport tehnic, un studiu de caz, un manual de utilizare, un alt document tehnic, ori dacă ați apelat la un sistem de asistență din cadrul unui program informatic, cel mai probabil un technical writer le-a redactat pe toate acestea.
Technical Writerul cercetează și structurează informațiile, folosindu-se de o varietate de medii de suport. În limba română nu există deocamdată un echivalent uzual folosit, așa că în continuare vom folosi abrevierea TechWr pentru a ne referi la cei care au această profesie.
Sarcina principală a unui TechWr poate fi definită ca "simplificare a complexității", prin mecanisme de structurare, sumarizare și reprezentare, astfel încât utilizatorul final să își poată atinge scopurile (de exemplu, să utilizeze corect un aparat electrocasnic sau un program de software).
Kurt Vonnegut sublinia că, spre deosebire de alte feluri de scriitură, vocea unui TechWr nu este evidentă în textul pe care îl scrie, acest fel de text fiind printre cele mai impersonale existente.
Recunoaște/Identifică nevoile utilizatorilor finali, îi cunoaște pe aceștia (de exemplu, te adresezi diferit unui configurator cu cunoștințe extinse privind programarea față de o persoană care nu știe programare dar care trebuie să poată să instaleze singură un program software). Un TechWr știe cine sunt utilizatorii finali, ce nevoi au aceștia, în ce context vor citi instrucțiunile și de ce, precum și cum. UX sau User Experience (experiența utilizatorului) este un factor important de luat în considerare, iar TechWr trebuie să țină cont în mod constant de felul în care utilizatorul final va folosi instrucțiunile (Kratchy 2017), incluzând cazul în care utilizatorul final nu parcurge instrucțiunile integral, ci doar secțiunea relevantă la un moment dat.
Adună toate informațiile relevante referitoare la utilizarea produsului de la programatori, ingineri, proiectanți sau alte persoane implicate în dezvoltarea acestuia, pentru a înțelege în detaliu cum funcționează acesta și cum interacționează cu utilizatorul final (Bellamy et al 2012). TechWr-ul este astfel și un tester, identificând adesea buguri, posibile disfuncționalități sau alte diferențe între cum e proiectat să funcționeze un produs sau software și cum funcționează acesta efectiv. Evident, acestea sunt raportate mai departe către echipa de dezvoltare/proiectare.
Colaborează cu cei care dezvoltă produsul/programul pentru a se asigura că instrucțiunile oglindesc realitatea. Tot în sarcina TechWr cade și protejarea potențialelor drepturi de autor, prin ne-divulgarea unor componente cum ar fi codul sursă, dacă este cazul.
Structurează toate informațiile într-un mod logic, coerent și ușor de urmărit (Boiko 2005). Ceea ce unor programatori li se poate părea de la sine înțeles, unui utilizator final i s-ar putea părea total confuz, iar rolul TechWr este de a acoperi orice astfel de diferențe.
Structurează și organizează informația astfel încât să fie cât mai ușor de înțeles de către utilizatorul final (Kratchy 2017). De multe ori, aceasta presupune o re-organizare fundamentală informației față de modul în care aceasta este structurată inițial.
Selectează modul cel mai potrivit de transmitere a informațiilor către utilizatori, începând de la manuale de instrucțiuni și până la video-uri instructive sau asistență în funcție de context.
Asigură consistența și coerența termenilor folosiți, adică același concept este descris prin același termen care la rândul lui, este scris în același fel. De exemplu, aceeași acțiune poate fi descrisă prin "faceți click", "apasă", sau "selectați", iar un utilizator mai puțin experimentat ar putea să încerce să efectueze trei acțiuni diferite. De asemenea, același element existent pe o pagină ar putea să fie scris în cinci moduri diferite: "info-field, Info Field, Infofield, InfoField, Info-Field" sugerând unui utilizator final riguros cinci elemente diferite, și nu unul și același. (Boiko 2005).
Primește feedback de la utilizatori și încearcă să acționeze și pe baza acestuia (clarificând ambiguitățile și îmbunătățind utilizabilitatea, dacă este posibil).
Profesia nu este deocamdată inclusă în COR, însă se fac eforturi în acest sens. Deși în România majoritatea TechWr lucrează în domeniul IT, aceștia nu sunt ingineri și nici absolvenți de studii tehnice. Deprinderile pe care le folosește un TechWr cel mai frecvent sunt legate de modul de comunicare a informației - iar aceasta din urmă trebuie să fie clară, ușor de urmărit și de înțeles. De aceea, abilitățile de comunicare și de structurare a informației au o greutate mai mare față de studiile tehnice. Desigur, există și TechWr care sunt absolvenți de studii tehnice care și-au dezvoltat deprinderile de "lucru cu informația".
Un TechWr identifică toate "asumpțiile" sau lucrurile ne-spuse și presupuse implicite de către echipa de dezvoltare și le explicitează în beneficiul utilizatorilor finali, pentru a preveni orice posibilă nedumerire. Un programator, de exemplu, poate presupune că toate calculatoarele pe care se va instala aplicația pe care o dezvoltă vor rula cel puțin Windows 7, însă dacă acest lucru nu apare inclus explicit în instrucțiuni, unii utilizatori poate vor încerca să instaleze programul și pe versiuni mai vechi, ca apoi să reclame că nu au reușit să instaleze cu succes programul sau că au avut parte de erori în cadrul procesului de instalare.
Un TechWr se asigură că jargonul folosit de echipa de dezvoltare este tradus în termeni ușor de înțeles de utilizatori. De exemplu, pentru un programator care lucrează timp de mai multe luni la aceeași aplicație, LP poate fi prescurtarea uzuală pentru "Launch Pad", însă pentru un utilizator LP poate fi de ne-înțeles, acesta așteptându-se ca termenul să apară cel puțin neprescurtat, dacă nu chiar sub altă denumire, cum ar fi "Home".
Un TechWr organizează și structurează informația în modul cel mai potrivit pentru utilizatorul final, un mod care poate fi diferit de modul în care aceasta a fost inițial proiectată de echipa de dezvoltare. În același timp, organizează și structurează și documentele, luând decizii despre când și cum să folosească imagini, liste, grafice sau subtitluri, pe de o parte, precum și alte informații de tipul "Atenționări", "Sugestii utile" etc. Pe de altă parte, rolul unui TechWr este și de a menține documentele clar structurate și ușor de parcurs, fără detalii inutile, reducând cât de mult posibil detaliile inutile sau superflue, precum și aglomerarea vizuală a instrucțiunilor (Gollner 2015).
Cum spuneam și mai sus, un TechWr se asigură că pentru aceleași noțiuni se folosesc și aceiași termeni (un buton va fi întotdeauna un buton, nu un dreptunghi, o tastă, un câmp sau altceva). De asemenea, un TechWr se asigură că se respectă și formatul "oficial", "agreat" al documentelor (the template) în cele mai mici detalii. Identitatea vizuală a numeroase companii este stabilită, de obicei, în cele mai mici detalii, iar utilizatorii finali sunt obișnuiți să vadă identitatea vizuală a unui brand în același fel.
Un TechWr se pune în locul utilizatorului final, încercând să identifice orice problemă pe care acesta ar putea să o aibă (de exemplu, poate observa la un moment dat că dispare o opțiune dintr-un meniu, deși în teorie ea ar trebui să fie acolo), sau orice neclaritate sau posibilă întrebare, încercând, în același timp, să o pre-întâmpine.
Un TechWr îndeplinește și rolul unui corector final al textului, asigurându-se că nu există greșeli gramaticale și de ortografie în acesta.
Prin urmare, un posibil răspuns la întrebarea "Ce este un TechWr?" ar fi "Totul". Iar un TechWr ar remarca imediat că întrebarea și răspunsul sună mai bine în limba engleză So, if the question is, "What is a technical writer?" the answer is, "Everything!" și ar încerca să propună o adaptare mai potrivită pentru limba română, de exemplu: "Ce face un Tech Wr?" cu răspunsul "Totul".
Munca alături de SMEs (Subject Matter Experts = experții în domeniu) vine cu o serie de provocări: de la comunicarea informațiilor la formalizarea funcționalităților. De cele mai multe ori, un TecWr trebuie să anticipeze problemele (non)tehnice și să identifice soluții pentru a extrage informația corectă de la SME. În exemplele de mai jos vom aborda câteva provocări ce pot apărea în munca cu programatorii.
Când poate un TechWr să documenteze funcționalitățile? Arată sprintul bine dacă documentația nu este finalizată până în ultima zi?
Documentarea unei funcționalități se poate realiza prin includerea unui story de documentație fie pe boardul echipei care dezvoltă funcționalitatea, fie pe boardul echipei de documentație care deservește toate echipele de dezvoltare. Prin includerea unui story pe boardul echipei de dezvoltare, ne asigurăm că funcționalitatea nu este încheiată și lansată în producție, până când aceasta nu este documentată, păstrând astfel în perfectă sincronizare ceea ce ajunge la client.
Cu toate acestea, în practică, aceasta nu este atât de evidentă. De multe ori, funcționalitatea este aproape gata, iar documentația așteaptă după ultimele modificări. Să zicem că este joi seara, buildul trece și sprintul este gata de a fi încheiat vineri. Documentația este finalizată vineri dimineața, intră în etapa de SME Review (recenzie). Persoana care a făcut recenzia mai are comentarii ce trebuie integrate în documentație, iar Scrum Masterul se plânge că iar trebuie să se aștepte după documentație, că nu se poate închide story-ul etc. În contextul descris anterior există de multe ori așteptarea ca documentația să fie gata în secunda 2 pentru a se putea închide story-ul și a se demonstra că sprintul este închis și angajamentul finalizat. Pentru a evita astfel de situații, o alternativă este desprinderea story-ului de documentație de sprintul echipei de dezvoltare. Astfel, echipele de dezvoltare își închid sprintul, iar echipa de documentație lucrează pe un board separat.
Păstrarea documentației pe un board separat mai are un avantaj. Dacă există funcționalități care necesită mai multe sprinturi/iterații pentru a fi finalizate, iar lansarea în producție nu coincide cu ultimul sprint de dezvoltare, atunci un TechWr poate monitoriza boardul de dezvoltare, poate urmări evoluția funcționalității, dar va crea un story de documentație doar după ce funcționalitatea este aproape finalizată.
Practic, în funcție de complexitatea funcționalității dezvoltate, documentația poate fi scrisă în cadrul sprintului în care se face dezvoltarea (Agile) sau la finalul mai multor sprinturi/iterații (Waterfall). Opțiunea de a include acest story pe boardul echipei de dezvoltare sau pe boardul echipei de documentație ține de cât de presate sunt echipele de dezvoltare să demonstreze cât progres a înregistrat doar activitatea de dezvoltare propriu-zisă. Opțiunea Waterfall poate părea mai sigură în sensul în care documentația se realizează doar după ce tot ciclul de dezvoltare-testare este complet. Dar dacă echipa de documentație lucrează doar așa și deservește mai mult de o echipă, finalizarea documentației poate reprezenta un blocaj enorm în lansarea unui produs, deoarece va fi prea mult de lucru într-un timp foarte scurt. Situația poate deveni critică dacă există lansări simultane de produse diferite și de versiuni diferite.
Un alt posibil exemplu de bună practică este despărțirea perioadei de dezvoltare de cea de testare, prin instituirea unui code freeze și alocarea unei perioade de timp (mai mult de o zi) destinate exclusiv testării și rezolvării disfuncționalităților identificate (bugurilor). După declararea code freeze-ului, documentația va putea fi scrisă și chiar testată în cadrul intervalului în care se efectuează doar testarea.
Concluzie O abordare Agile pentru funcționalitățile de complexitate mică (sau funcționalități dezvoltate peste o funcționalitate deja existentă) și o abordare Waterfall pentru funcționalitățile de complexitate mare (sau funcționalități complet refactorizate) reprezintă o abordare hibridă corectă, care nu blochează lansările în producție. Cât despre includerea unui story de documentație pe board-ul echipelor de dezvoltare sau pe boardul echipei de documentație, acest aspect ține de maturitatea echipei și de conștientizarea faptului că documentația este finalizată doar după ce toate elementele ce țin de dezvoltare-testare sunt clarificate. Dar dacă acestea se concretizează în (pen)ultima zi de sprint, acesta din urmă nu va fi încheiat cu un procent de 100%.
Cât de multă informație trebuie dată unui utilizator final care dorește să folosească produsul și să-și atingă scopurile?
Programatorii sunt persoane cu gândire analitică, sistematică, ordonată. Munca unui programator poate fi influențată de informația limitată care i se dă pentru a dezvolta o funcționalitate, de informația exhaustivă pe care o deține despre un anumit subiect (cu riscul pierderii în detalii), de urgența cu care trebuie să rezolve un defect, de propriul mod de gândire.
Programatorul primește o sarcină clară: trebuie adăugat un buton care permite ștergerea unei resurse. Implementarea unui buton ce corespunde unei operații CRUD nu este foarte dificilă, dar dacă programatorul nu ia în calcul condițiile și contextul în care se poate efectua operația, deși sarcina este realizată cu succes, această funcționalitate nu va avea o documentație cu adevărat utilă. Ce se întâmplă dacă resursa are sub-resurse? Ce se întâmplă cu procesele care folosesc activ resursa? Este notificat utilizatorul care folosește activ resursa de ce nu o mai poate accesa? În practică, dependințele dintre componente sunt de multe ori explicate vag în specificații și luate în calcul parțial când se dezvoltă o funcționalitate nouă. Este obligația TechWr să semnaleze faptul că deși utilizatorul poate reproduce pașii operației de ștergere a unei resurse, acesta nu va înțelege complet și corect consecințele acțiunilor sale. Documentația este în această situație destul de inutilă, iar programatorii trebuie să reia dezvoltarea și să rezolve probleme precum accesul, interdependența, influența asupra sistemelor conexe.
O funcționalitate incompletă înseamnă o documentație incompletă. În unele cazuri, documentația nu detaliază anumite aspecte contextuale, deoarece funcționalitatea nu a fost gândită de la bun început contextual.
Programatorul a lucrat la o funcționalitate de o bună bucată de timp și cunoaște tot ce se poate despre aceasta. TechWr documentează părțile relevante pentru utilizator, dar programatorul spune că nu este suficient. De multe ori, programatorii doresc ca documentația destinată utilizatorului final non-tehnic să includă etapele care au stat la baza realizării aplicației, tehnologiile utilizate, apelarea backend a componentelor.
TechWr trebuie să asculte tot, dar să includă doar ce este relevant pentru utilizatorul final și să convingă programatorul că oricât de mare sau igenios a fost efortul de a realiza funcționalitatea, utilizatorul final dorește (așa cum îi spune și numele) să utilizeze un produs nu să îi decodeze sau să îi descopere componentele.
Programatorul primește un defect sau un bug de rezolvat până la finalul sprint-ului. Nu există workaround, deci problema trebuie rezolvată în cod. Programatorul găsește o soluție rapidă, dar care va genera probleme pe viitor dacă nu se fac modificări sistemice. Programatorul găsește însă și o soluție care să rezolve nu simptomul, ci cauza, dar pentru care are nevoie de mai mult timp decât intervalul alocat. Constrâns de timp, programatorul va alege prima variantă, ceea ce pentru TechWr înseamnă explicații mai mult sau mai puțin prietenoase pentru utilizator de tipul: limitări, notă importantă, atenționări etc.
Ideal, ulterior momentului de criză, programatorului i se dă timp să elimine cauza, dar dacă acest lucru nu se întâmplă se ajunge în situația în care lista de comportamente speciale sau de limitări să fie mare, greu de întreținut de TechWr și greu de gestionar de utilizator. Un TechWr nu va putea compensa la nesfârșit rezolvările de moment.
Programatorul a dezvoltat o funcționalitate care permite utilizatorului să selecteze o opțiune și o valoare, dintr-o listă implicită. Programatorul trebuie să facă selecția flexibilă și să permită utilizatorului să adauge și opțiuni/valori customizate prin editare de la tastatură. Să presupunem că funcționalitatea se referă la posibilitatea utilizatorului de a configura formatul unei unități de măsură. Pentru a configura acest format, utilizatorul poate tasta sau selecta o valoare din lista de valori implicită. TechWr documentează toate aceste aspecte, dar i se spune că nu a documentat tot. Ce credeți că a uitat TechWr? Programatorul a implementat un sistem prin care valorile default să poată fi anulate și refolosite cu un alt scop. Pentru ca utilizatorul să poată recalibra valoarea implicită (pentru ca aceasta să poată fi folosită cu alt scop), utilizatorul trebuie să folosească comanda escape (prin utilizarea simbolului "\" urmat de valoarea implicită). Mai mult, utilizatorul poate introduce valori noi pe lângă cele implicite punând string-uri între ghilimele ("string" sau 'string'). Interfața nu sugerează utilizatorului această posibilitate și nici specificațiile tehnice nu menționează nimic legat de detaliile acestei implementări.
Programatorul va gândi în cele mai multe cazuri prin prisma scrisului de cod. Programatorului i s-a părut normal să implementeze flexibilitatea prin intermediul simbolurilor de tip escape sau ghilimele, din moment ce aceste simboluri sunt lucruri clasice, încetățenite în scrierea de cod, cu precădere în limbajul C pentru inițializarea de valori noi. Utilizatorul final nu are cum să ghicească aceste convenții, deoarece în majoritatea cazurilor utilizatorul final nu este și nu gândește precum un programator.
Un TechWr trebuie să explice și să expună aceste aspecte în documentație. Există două consecințe ale acestei implementări. Pe de o parte, TechWr învață cum gândesc programatorii, se familiarizează cu convențiile scrisului de cod, se obișnuiește să poată anticipa ce să-i întrebe pe programatori. Practic, un TechWr trebuie să învețe bazele programării. Pe de altă parte, se constată faptul că implementarea în sine, deși corectă, este ciudată pentru utilizatorul final care nu vorbește aceeași limbă cu programatorul. O consecință benefică ar fi regândirea implementării, astfel încât capacitatea de a reseta valorile implicite să se regăsească mai ușor în interfață. Un TechWr poate atrage atenția asupra acestui aspect.
Cum putem să ne asigurăm că avem o documentație extensibilă și sustenabilă?
Echipa de management decide ca anumite module să fie desprinse din produse deja existente cu intenția de a fi integrate în toate produsele companiei. Din moment ce aceste module sunt deja documentate în unele capitole ale unui produs, nu e greu să luăm informația și să o includem în restul documentației, corect? Dacă răspunsul la această întrebare ar fi afirmativ, sarcina unui TechWr ar fi de a face de multe ori copy-paste din stânga în dreapta. De multe ori, cam asta își imaginează managementul că face un TechWr. Dacă acel conținut a fost scris într-un limbaj markup de tip XML sau Markdown, dacă acel conținut are o versionare corectă și este gestionat dintr-un sistem centralizat, atunci extragerea și reintegrarea acestuia în documentația altor produse este mai ușoară, mai logică, mai sustenabilă. Dacă acel conținut este stocat într-un document de tip Word sau un PDF, acesta va trebui migrat, rescris și integrat cu un efort destul de mare.
Documentația este sustenabilă dacă este modulară sau granulară, dacă este standardizată, dacă este structurată, dacă este clară/corectă, dacă este reutilizabilă, dacă este îmbogățită semantic, dacă este centralizată. Pentru realizarea acestui lucru este nevoie de aderarea la un stil de lucru centrat pe paradigma de scriere potrivită domeniului despre care scriem (avem directive internaționale diferite pentru scrierea de instrucțiuni pentru utilaje vs. software) și de instrumente care să permită informației să fie transferabilă și interpretabilă: de editoare, de instrumente de stocare, de instrumente de publicare sau de sisteme ce integrează realizarea de conținut end-to-end adică de sisteme (C)CMS, dar despre acestea vom discuta în partea a doua a acestui articol.
Un TechWr este o resursă cheie în orice echipă de dezvoltare a unui produs software. Dacă încă nu sunteți pe deplin convinși, vă invităm să citiți și partea a doua a acestui articol, ce va apărea într-un număr următor.
Achteling, M. - Component-based Content Management Systems, indoition.com, https://www.indoition.com/online-help-authoring-tools-survey.htm\#section_market_leaders
Bellamy, L.; Carey, M. & Schlotfeldt, J., (2012) - DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, IBM Press.
Boiko, B., (2005) - Content Management Bible, USA - UK: John Wiley&Sons.
Buehling, B. (2015) - Anatomy of an enterprise structure authoring system, tcworld Conference 2015
Cameron, S., (2011) - Enterprise Content Management: A Business and Technical Guide, BCS.
Closs, S. (2016) - DITA- the Topic-Based XML standard: a quick start, New York - London: Springer.
Gollner, J. (2015) - Practical steps towards integrated content management, tcworld Conference 2015
Kratchy, R. (2017) - Turning legacy documentation into user story based content, tcworld Conference 2017
Society for Technical Communication, - What is Technical Writing?, https://www.stc-psc.org/what-is-technical-writing/