ABONAMENTE VIDEO REDACȚIA
RO
EN
NOU
Numărul 147
Numărul 146 Numărul 145 Numărul 144 Numărul 143 Numărul 142 Numărul 141 Numărul 140 Numărul 139 Numărul 138 Numărul 137 Numărul 136 Numărul 135 Numărul 134 Numărul 133 Numărul 132 Numărul 131 Numărul 130 Numărul 129 Numărul 128 Numărul 127 Numărul 126 Numărul 125 Numărul 124 Numărul 123 Numărul 122 Numărul 121 Numărul 120 Numărul 119 Numărul 118 Numărul 117 Numărul 116 Numărul 115 Numărul 114 Numărul 113 Numărul 112 Numărul 111 Numărul 110 Numărul 109 Numărul 108 Numărul 107 Numărul 106 Numărul 105 Numărul 104 Numărul 103 Numărul 102 Numărul 101 Numărul 100 Numărul 99 Numărul 98 Numărul 97 Numărul 96 Numărul 95 Numărul 94 Numărul 93 Numărul 92 Numărul 91 Numărul 90 Numărul 89 Numărul 88 Numărul 87 Numărul 86 Numărul 85 Numărul 84 Numărul 83 Numărul 82 Numărul 81 Numărul 80 Numărul 79 Numărul 78 Numărul 77 Numărul 76 Numărul 75 Numărul 74 Numărul 73 Numărul 72 Numărul 71 Numărul 70 Numărul 69 Numărul 68 Numărul 67 Numărul 66 Numărul 65 Numărul 64 Numărul 63 Numărul 62 Numărul 61 Numărul 60 Numărul 59 Numărul 58 Numărul 57 Numărul 56 Numărul 55 Numărul 54 Numărul 53 Numărul 52 Numărul 51 Numărul 50 Numărul 49 Numărul 48 Numărul 47 Numărul 46 Numărul 45 Numărul 44 Numărul 43 Numărul 42 Numărul 41 Numărul 40 Numărul 39 Numărul 38 Numărul 37 Numărul 36 Numărul 35 Numărul 34 Numărul 33 Numărul 32 Numărul 31 Numărul 30 Numărul 29 Numărul 28 Numărul 27 Numărul 26 Numărul 25 Numărul 24 Numărul 23 Numărul 22 Numărul 21 Numărul 20 Numărul 19 Numărul 18 Numărul 17 Numărul 16 Numărul 15 Numărul 14 Numărul 13 Numărul 12 Numărul 11 Numărul 10 Numărul 9 Numărul 8 Numărul 7 Numărul 6 Numărul 5 Numărul 4 Numărul 3 Numărul 2 Numărul 1
×
▼ LISTĂ EDIȚII ▼
Numărul 94
Abonament PDF

Abilitățile unui Technical Writer (I) Ce este? Ce face?

Sonia Pavlenko
Technical Writer @ Accenture Industrial Software S



Melania Duma
Technical Writer @ SDL Plc



DIVERSE

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.

Ce e un TechWr?

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.

Ce face un TechWr?

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".

De ce e bine să ai în echipă și un TechWr?

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".

Ce provocări are un TechWr care lucrează cu programatori?

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.

Integrare și iterații

Când poate un TechWr să documenteze funcționalitățile? Arată sprintul bine dacă documentația nu este finalizată până în ultima zi?

Situație

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%.

Utilitate și exhaustivitate

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.

Situația 1: O funcționalitate incompletă va avea o documentație incompletă.

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.

Concluzia 1

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.

Situația 2: Trebuie evitată acordarea de prea multe detalii tehnice unui utilizator non-tehnic.

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.

Concluzia 2

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.

Situația 3: Documentația nu poate compensa și motiva la nesfârșit problemele unui produs.

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.

Concluzia 3

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.

Situația 4: Un TechWr trebuie să cunoască bazele programării.

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.

Concluzie

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.

Relevanță și extensibilitate

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.

Concluzie

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.

Resurse

  1. Achteling, M. - Component-based Content Management Systems, indoition.com, https://www.indoition.com/online-help-authoring-tools-survey.htm\#section_market_leaders

  2. Bellamy, L.; Carey, M. & Schlotfeldt, J., (2012) - DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, IBM Press.

  3. Boiko, B., (2005) - Content Management Bible, USA - UK: John Wiley&Sons.

  4. Buehling, B. (2015) - Anatomy of an enterprise structure authoring system, tcworld Conference 2015

  5. Cameron, S., (2011) - Enterprise Content Management: A Business and Technical Guide, BCS.

  6. Closs, S. (2016) - DITA- the Topic-Based XML standard: a quick start, New York - London: Springer.

  7. Gollner, J. (2015) - Practical steps towards integrated content management, tcworld Conference 2015

  8. Kratchy, R. (2017) - Turning legacy documentation into user story based content, tcworld Conference 2017

  9. Society for Technical Communication, - What is Technical Writing?, https://www.stc-psc.org/what-is-technical-writing/

  10. Weinert, A. & Brueggermann, M. E. (2012) - Wiki as CMS, tcworld magazine, June 2012 - http://www.tcworld.info/e-magazine/technical-communication/article/wiki-as-a-cms/

Conferință TSM

NUMĂRUL 147 - Automotive

Sponsori

  • Accenture
  • BT Code Crafters
  • Accesa
  • Bosch
  • Betfair
  • MHP
  • BoatyardX
  • .msg systems
  • P3 group
  • Ing Hubs
  • Cognizant Softvision
  • Colors in projects