De ce să nu fii technical writer

Technical writingul este o meserie foarte interesantă… dar asta nu înseamnă că e potrivită pentru oricine.

Deci, e posibil să nu ți se potrivească jobul ăsta dacă:

  • Cauți un job creativ.
    Când scrii documentație tehnică e o greseală să fii prea creativ în exprimare – textul tău trebuie să urmeze niște standarde clare, iar utilizatorul vrea să știe cum se folosește softul tău, nu să citească metafore și epitete. În plus, există șanse mari ca utilizatorii documentației să nu fie vorbitori nativi de engleză, caz în care cuvintele prea sofisticate o să îi încurce în loc sa îi ajute.
  • Ești complet asocial/ă.
    Nu, nu e nevoie să fii BFF cu toată firma, dar tot jobul ăsta se învârte in jurul comunicării (de altfel, domeniul în sens larg este cunoscut drept „comunicare tehnică” sau „technical communication”). Trebuie să fii capabilă să te înțelegi cu toată lumea, și mai ales să găsești abordarea corectă în fiecare caz pentru a obține informațiile de care ai nevoie. (Ca să fim sinceri până la capăt, în foarte puține firme documentația este considerată o prioritate, deci de multe ori va trebui să dai din coate pentru a face rost de tot ce ai nevoie. Nu e un domeniu potrivit pentru oameni excesiv de timizi.)
  • Ești complet atehnic/ă.
    În funcție de firmă, asta poate să fie un dezavantaj sau poate chiar să te scoată complet din calcul. Chiar și atunci când documentezi strict partea funcțională a unei aplicații, tot va trebui să te ocupi și de chestii mai tehnice. De exemplu, multe firme au un singur technical writer, deci va trebui să fii propriul tău suport tehnic și nu o sa ai la cine să fugi imediat ce vezi o eroare. Dacă firma are nevoie de documentație pentru un SDK, nu vei avea nici o șansă dacă tu ai auzit de variabile doar la matematică și nu știi ce e o metodă.
  • Vrei să fii în centrul atenției
    Technical writerul este în general omul din umbră. Șansele să obții o statuie în fața firmei sunt minime, munca ta va fi remarcată mai ales când ratezi ceva, iar alte echipe vor primi mai multe laude chiar și dacă proiectul a avut succes.

RoboHelp: Optimizare pentru search, partea 1

Premisa

Avem un sistem de online help destul de mare – aproximativ 6000 de topicuri în 40 de module separate – generat din RoboHelp, în format WebHelp, și livrat atât pe un site, cât și ca MSI.

Problema

Searchul durează prea mult – 25-30 secunde de pe server. Dacă helpul e instalat local, searchul e mult mai rapid, dar majoritatea clienților folosesc site-ul.

Motivele

După câteva runde de teste și multe căutări pe Google, am ajuns la concluzia că cea mai mare parte a vinei o poartă searchul din RoboHelp (dar niște îmbunătățiri la nivel de structură a helpului nu ar strica nici ele).

Soluțiile

Cum modificările la nivel de conținut al helpului sunt mai greu de pus in practică pe termen scurt, am început să testez diverse opțiuni de a face searchul mai eficient.

Încercarea 1: Fără căutări in PDF si Word.

Pentru că fiecare modul are o versiune PDF care conține fix același lucru ca online help-ul, mai întâi am exclus toate documentele de genul asta din căutări.

optimize_search_exclude

Rezultat: nici o îmbunătățire de performanță. (Dar cred ca oricum a fost o idee bună, pentru că măcar nu va mai apărea conținut duplicat în căutări.)

Încercarea 2: Căutare implicită cu toți termenii

Pentru că in RoboHelp 2015 există o opțiune nouă în acest sens, am setat ca toate modulele să aibă căutarea cu „AND” activată by default.

optimize_search_and

Rezultat: nici o îmbunătățire de performanță (dar nici nu mă așteptam). Nu știu de ce a trebuit să așteptăm atâția ani pentru o setare la mintea cocoșului, dar bine că a apărut. Acum searchul ar trebui să funcționeze așa cum probabil își imagina toată lumea ca merge deja.

Încercarea 3: Optimizare pentru LAN

Da, nu e prea intuitiv, totuși noi publicăm pe internet. Well, se pare că opțiunea și-a păstrat denumirea din negurile dial-up-ului.

Niște background întâi: pentru căutare, RoboHelp generează niște fișiere (cu nume de forma package_n_xml.js) în folderul whxdata. La fiecare search e încărcat fiecare fișier de genul ăsta… și cu cât mai multe fișiere, cu atât mai multe requesturi către server și cu atât mai lent va merge totul. Aici intervine opțiunea noastră: când outputul este optimizat pentru internet, sunt generate multe fișiere package mici (pentru că, pe vremuri, asta ar fi fost mai eficient, bănuiesc); când outputul este optimizat pentru o rețea locală, sunt generate mai puține fișiere package mai mari.

optimize_lan

Așa că… am început să fac comparații, după ce am generat întreg sistemul de help cu fiecare dintre opțiuni:.

  • O căutare in Windows pe stringul package*.js, în tot sistemul de help: varianta optimizată pentru LAN are de 6 ori mai puține fișiere package.
    optimize_compare_package
  • O comparație la nivel de merged project: varianta optimizată pentru LAN are de 6 ori mai puține fișiere in folderul whxdata și în loc de 41 de package-uri am obținut 2.
    optimize_compare_folder
  • O comparație în Chrome Developer Tools: în varianta optimizată pentru LAN se trimit 190 de requesturi, față de 275 în varianta optimizată pentru internet.
    requests_optimize_compare

Întrebările (la care nu am încă răspunsuri clare):

  • De ce nu se trimit de 6 ori mai puține requesturi? După o analiză sumară în Developer Tools, deduc că pentru fiecare modul par să se trimită minim 5 requesturi: packageindex_xml.js, package_0_xml.js, synonym_xml.js, topictableindex_xml.js și topictable_0_xml.js, deci de la un punct încolo singura modalitate de îmbunătățire a performanței e scăderea numărului total de module.
  • De ce în cazul optimizat pentru LAN se descarcă de 5 ori mai multe date decât în cealaltă variantă, mai ales având în vedere că se fac mai puține requesturi?

Rezultat: o îmbunătățire aproape insesizabilă de performanță, mult mai puțin decât speram.

Concluzia finală

După o lună de teste, știu mult mai multe despre searchul RoboHelpului… și am reușit să optimizez căutarea cu 5 secunde (în zilele în care zbârnâie internetul).

Ce urmează?

Două chestii:

  • Consolidare de module – mai puține module, mai puține fișiere, mai puține requesturi, search mai rapid.
  • Implementarea unui search extern – Google custom search sau Zoom Search.

Cum ajungi technical writer în România?

Să zicem că te-ai lămurit ce înseamnă meseria asta și ți se pare interesantă. Câte șanse ai să te angajezi în domeniu în România? Destul de multe, în momentul de față, din două motive:

  • Industria este foarte mică – la ultima mea numărătoare, pe LinkedIn erau cam 100 de technical writeri în vreo 50 companii și, chiar luându-i în considerare pe care care nu au profil, tot nu se ajunge la un numar prea mare.
  • In România nu există nici un curs de technical writing în învățământul superior*, iar singura diplomă oarecum relevantă de care știu eu este cea de master în Teoria si Practica Editării de la Facultatea de Litere din București.
    (* În afara sistemului de învățământ, există GuideTC, o firma care ofera traininguri în domeniu, printre care și unul de „bazele technical writingului”. Nu am interacționat cu ei, deci nu știu nimic în afară de faptul că există.)

Pe scurt, multe companii nu își prea permit să aibă pretenții și, daca ai experiență transferabilă, ai mari șanse să convingi pe cineva că esti candidatul potrivit.

Experiența relevantă

Din ce am văzut eu (pe LinkedIn si la fostii sau actualii mei colegi), majoritatea technical writerilor care lucrează în momentul de față in România au background în:

  • Traduceri
  • Jurnalism
  • Content writing
  • Redactare de carte
  • Învățământ
  • Training
  • Domeniul de activitate al firmei angajatoare (adică background în finanțe pentru firmele care fac software financiar, absolvenți de Politehnică pentru firmele care au nevoie de documentație de API, etc).

Limba engleză

În majoritatea cazurilor, o limbă straină (în general engleza) este o cerință obligatorie – de câțiva ani de când urmăresc anunțurile de angajare am văzut un singur job care presupunea documentație scrisă în română. Și când zic „cerință obligatorie” mă refer la limba vorbită la perfecție, aproape de nivelul nativ – clienții care îți citesc documentația nu trebuie sa își dea seama ca a fost scrisă în România (sau în India, sau în Ungaria, sau…), trebuie să se poată concentra asupra informațiilor din ea fără să se blocheze în greșeli gramaticale sau întorsături de frază ciudate. (Da, da, „toți românii știu engleză” – așa aveam și eu impresia acum câțiva ani. Între timp, mi-am dat seama că foarte mulți candidați își supraestimează abilitățile…)

 

Ce înseamnă technical writing?

Meseria de technical writer începe să devină din ce în ce mai populară în România, dar puțini oameni chiar știu ce presupune. În ultimii câțiva ani am primit nenumărate priviri confuze, așa că mi-am facut o listă de explicații standard, in funcție de audiență.

Explicația pentru părinții mei: Știi că atunci când primești un mixer nou ai instrucțiuni de folosire? Ei, cam aia fac eu, numai că nu le traduc prin Google Translate din chineză.

Explicația pentru prietenii mei: Știi helpul de la Word? Ei, cam aia fac eu, dar pentru alt soft.

Explicația pentru colegii mei: Știi specificațiile pe care le scrii tu? Eu le traduc în ceva ce poate fi înțeles de client.

Explicația pentru candidații pe care îi intervievez: Treaba noastră e să le explicăm utilizatorilor ce face aplicația noastră – ceea ce poate include instrucțiuni de instalare, configurare, administrare și/sau utilizare propriu-zisă.

Și acum pe bune… ce faci în fiecare zi?

În ciuda numelui, partea de scris efectiv este un procent mai mic decât ați crede… foarte pe scurt, pașii sunt cam așa:

  1. Cercetare. Aici aduni informații din toate sursele posibile (documente pierdute pe intranet, specificații pe wiki-ul intern, mailuri forwardate, ideea genială a programatorului de la etajul 2, și asa mai departe).
  2. Structurare. Aici pui cap la cap informațiile de la pasul 1, într-o structură care are sens.
  3. Editare. Aici citești și reformulezi și citesti iar și reformulezi iar, până când totul e fix atât de concis și de clar cât trebuie.
  4. Publicare. Aici opera ta ajunge la clienti!

Bonusuri:

  • Testezi dacă aplicația chiar funcționează cum scrie in specuri.
  • Loghezi buguri când descoperi că nu.
  • Te enervezi dacă programatorii au folosit un termen greșit în interfață
  • Te bucuri dacă descoperi că au niște standarde pe care le urmează…
  • …sau scrii chiar tu standardele.
  • Înveți să traduci din romgleză, frangleză si chingleză într-o engleză literară (dar nici prea literară, nu suntem Shakespeare).
  • Te bucuri când în sfârsit o să reușești să reformulezi ceva în cel bun mod.
  • Te enervezi când clientul îți loghează un bug despre o funcționalitate care nici măcar nu era menționată in specificații.