De ce să fii technical writer

Orice meserie se poate învăța dacă depui efortul, dar dacă te regăsești în lista de mai jos o să îți fie mult mai ușor ca technical writer.

  • Ai talent la scris și la editat.
    Prima parte era evidentă, a doua mai puțin… și eu aș zice că talentul la editat e chiar mai important decât talentul la scris. Dacă poți să compui un text care explică un proces sau un concept, după care să îl reformulezi până nu mai are urmă de ambiguitate sau vreun cuvânt inutil, atunci e posibil să îți fi găsit meseria ideală.
  • Știi foarte bine o limbă străină (in general engleza, dar ocazional mai apar și joburi pe germană, franceză sau română).
    Aici e clar – dacă scrii la fel de bine ca un nativ, deja ești mai bine poziționat decât 90% din candidați.
  • Știi gramatică (și te și interesează să scrii corect gramatical).
    Mai exact, e important să înțelegi logica gramaticii și să poți urma un ghid de stil, chiar dacă nu îți mai amintești ce înseamnă o apoziție. Nici măcar nu e neapărată nevoie sa știi la perfecție gramatica limbii străine în care scrii – majoritatea conceptelor sunt aplicabile (aproape) universal.
  • Ești atent/ă la detalii.
    Da, asta e un clișeu și apare în atât de multe anunțuri de joburi, dar in cazul asta e chiar important. In documentația tehnică toate mărunțișurile contează, de la descrierea celei mai mici bife până la aranjarea documentului în pagină și spațierea dintre rânduri. Un manual nu va arăta niciodată profesionist dacă e scris pe fugă.
    P.S. Să nu ai niciodată încredere în ce primești de la alte echipe. Pe ei mai mult ca sigur nu îi interesează dacă fereastra aia se numește Rules sau Rule, dar ție își pasă.
  • Poți să comunici eficient cu oricine.
    Nu întâmplător oamenii care fac jobul sunt cunoscuți și sub numele de technical communicators. Rolul tău e să obții niște informații și pentru asta trebuie să știi cum să abordezi oamenii. Dacă apari neanunțat la biroul colegului super-ocupat, e foarte posibil să nici nu afli ce te interesează, și să și pici pe ultima poziție în lista lui de priorități. Pe de altă parte, dacă ai nevoie de un demo live și colega îți propune să te limitezi la două propoziții într-un mail… aici trebuie să se vadă puterea ta de convingere.

RoboHelp: Automatizare prin batch (rhcl.exe)

Deși multă lume pare să nu știe de ea, versiunea command line a RoboHelp-ului poate fi extrem de utilă pentru automatizarea (parțială sau totală) a build-urilor de help.

Ce este rhcl.exe?

Numele utilitarului vine de la RoboHelp Command Line și îți permite să generezi un SSL fără să deschizi RoboHelp-ul în sine. Pentru sisteme mici de documentație, efortul de a da dublu-click pe un .xpj e neglijabil, dar dacă ai 20 de module, s-ar putea să aștepți mai mult să se deschidă modulul decât durează buildul propriu-zis… și aici intervine rhcl.

Cum se folosește?

Foarte simplu, pentru că are doar câțiva parametri (pe care nu o să îi enumăr aici, pentru că sunt disponibili în documentația de la Adobe).

O linie de comandă foarte simplă e de forma:

rhcl c:\sources\project1\project1.xpj -l WebHelp -o c:\builds\project1

În traducere, mai întâi e numele executabilului, apoi (fără nici un parametru) path-ul unde se află xpj-ul proiectului pe care vrei să îl generezi, apoi (cu parametrul -l) numele layout-ului care trebuie generat, iar la sfârșit (cu parametrul -o) locul unde se generează fișierele.

Pentru ce am eu nevoie la muncă, parametrii ăștia sunt suficienți. Dacă vrei, poți să folosești rhcl și ca să publici un layout (cu opțiunea -p) sau să generezi loguri (cu opțiunea -g), dar eu nu lucrat prea mult cu asta.

Batch-ul meu arată ceva de genul asta:

Alte idei

Nu le-am testat personal, dar în teorie rhcl ar putea fi folosit ca parte a unui sistem mai complex, de exemplu unul care să republice în fiecare zi documentația modificată în ziua anterioară, urmând pașii:

  1. Update automat al documentației din source control (folosind interfața command line a sistemului de source control).
  2. Generare batch pe hardul local (folosind rhcl).
  3. Publicare batch pe un server (folosind rhcl).

Tips & tricks/Troubleshooting

  • Dacă liniile tale de comandă încep cu rhcl, trebuie ca fișierul .bat să fie salvat în folderul în care se găsește și rhcl.exe. Dacă, în loc de rhcl simplu, folosești path-ul absolut către executabil (de exemplu C:\Program Files (x86)\Adobe\Adobe RoboHelp 2015\RoboHTML\rhcl.exe), poți să salvezi fișierul .bat oriunde pe hard.
  • Dacă orice path conține spații, trebuie să fie pus între ghilimele.
  • rhcl probabil că nu este prea sus pe lista de priorități a celor de la Adobe, deci nu e întotdeauna testat cum trebuie. În RoboHelp 2015, dacă încercai să generezi helpul folosind rhcl și aveai conditional build tags excluse din SSL, outputul nu era corect (tot conținutul care avea un tag era exclus, chiar dacă în SSL apărea ca inclus). Bugul a fost rezolvat în update-ul 2.
  • Unele module refuză să se genereze prin batch, fără un motiv evident. Nu am o soluție în afară de generat modulul respectiv de mână (din interfața RoboHelp).
  • În RoboHelp 2015, dacă nu poți genera nimic prin batch, instalează update-urile KB2758694 and KB954430 de la Microsoft.

Agile sau nu

Din seria haz de necaz, o comparație între Agile (ăla de pe hârtie) și Dirty Agile (ăla care se întâmplă în realitate). Partea mea favorită în momentul de față:

Non-Agile: Full specifications up-front

Agile: Flexible user stories over time

Dirty Agile: Specifications?

…zise ea, scrollând printre zeci de user stories fără nici nici un fel de detalii…

Evolution of Technical Communication (ETC), Sofia, Bulgaria, 2-3 iunie

etc_logo_orig_bPentru că, aparent, vecinii noștri bulgari ne-au luat-o înainte la capitolul documentație tehnică, la începutul lui iunie va avea loc o conferință foarte interesantă la Sofia. Conferința ETC (Evolution of Technical Communication) va avea loc pe 2 și 3 iunie, iar prețul de early bird (până pe 8 mai) este de 70 euro pentru ambele zile.

Ca o paranteză, cele două evenimente legate de technical writing la care am fost eu până acum (Graphic Design and Tools for Technical Writers și Single Source Publishing Using DITA and DITA Tools) au fost interesante pentru mine ca ocazii de networking, dar mai puțin din punctul de vedere al informațiilor pe care le-am obținut – partea de grafică nu e prea importantă în munca mea de acum, iar introducerea în DITA a fost la nivel de începători absoluți și a constat în cea mai mare parte în lucruri pe care le știam deja. La Tekom Roadshow nu am mers pentru că părea axat pe DITA, iar șansele ca eu să mă ocup cu așa ceva în viitorul apropiat erau (și sunt) minime, deci nu se justifica investiția. (…Serios, toată Europa lucrează în DITA și noi suntem singurii ciudați care au ales RoboHelp?!)

Închizând paranteza, conferința bulgarilor este mult mai complexă (chiar merită cei 70 euro), iar subiectele de discuție par mai variate. Cele care m-ar interesa pe mine în mod deosebit sunt:

  • George Bina, Syncro Soft (Craiova) – am folosit pentru câteva luni oXygen, softul craiovenilor, și am rămas extrem de impresionată de asistența extraordinară pe care o oferă pe forum (chiar și nenumăraților useri – ca mine – care de fapt se pierdeau în subtilitățile DocBook-ului, nu în oXygen!). Prezentarea se numește Single-Source Publishing Using Multiple Formats, dar sincer m-aș duce indiferent de subiect. Acum vreo 2 ani angajau un technical writer și atunci chiar mi-a părut rău că nu locuiesc in Craiova.
  • Sissi Closs (profesoară la Universitatea de Științe Aplicate din Karlsruhe), cu prezentarea The tekom Profiling Tool: How to Define Job Roles and Competence Profiles for Technical Writers, care sună a ceva care mi-ar fi foarte de ajutor la muncă, unde sunt implicată și în procesul de recrutare, și în training.
  • Vanya Kiritzova și Margarita Staneva (VMWare Bulgaria), despre o carieră în technical writing – Plot Your Technical Writing Career Like a Pro. Eu personal sunt mulțumită de traiectoria mea profesională de până acum, dar întotdeauna e util să auzi idei noi.
  • Axel Luther (SAP Germania), despre documentație video (Product and Instructional Videos – A Perfect Supplement to Classical Product Documentation)… pentru că eu urăsc să mă uit la videoclipuri și nu înțeleg de ce ar vrea cineva să se tortureze așa 😀 (Și pentru că accept faptul că documentația mea se adresează unor clienți care probabil nu gândesc ca mine, deci va trebui să învăț mai mult și despre partea video.)
  • Dimiter Simov și Ekaterina Mitova (SAP Bulgaria), cu prezentarea Are You Ready for User Feedback?, o întrebare care se aude din ce în ce mai des în ședințele departamentului meu…
  • Lukasz Gornicki (SAP Polonia) – Documenting REST API (workshop), pentru că se pare că documentația de API e viitorul și eu sunt puțin în urmă 🙂
  • Yordan Ugrinov (VMWare Bulgaria), un workshop cu titlul Web Analytics for Documentation: Use Cases, Best Practices, and Caveats. Încă o dată subiectul potrivit la momentul potrivit, pentru că recent am implementat Google Analytics pentru produsul pe care lucrez și… recunosc că nu prea știu la ce ar trebui să mă uit.

(Dacă lista asta pare lungă, mergeți pe site-ul ETC – chiar am făcut o selecție, programul complet este mult mai variat.)

Cu puțin noroc, dacă se aliniază planetele, release-urile și zilele de concediu, ne auzim cu un aproape-live-blogging din Sofia peste o lună și ceva!

RoboHelp: Cum să faci modificări bulk în SSL-uri

Interfața din RoboHelp este destul de intuitivă, iar o dată ce ai înțeles ce face fiecare opțiune nu e greu să generezi un sistem de online help. Dar ce te faci dacă trebuie să faci multe schimbări – cum ar fi, de exemplu, să modifici o setare in WebHelp pentru 40 de module? Opțiunea „simplă” este să deschizi fiecare modul, să dai dublu-click pe SSL, să navighezi la pagina corespunzătoare din wizard, să faci modificarea, să salvezi, să deschizi următorul modul… și tot așa de 40 de ori. Opțiunea mai inteligentă e să îți dai seama că (așa ca mai toate fișierele din RoboHelp) SSL-ul este un XML relativ ușor de manipulat.

Metoda de mai jos se poate aplica pentru orice setare din GUI (și chiar pentru unele care nu sunt vizibile). În exemplul următor, voi presupune că am mai multe module, cu cel puțin un SSL deja definit în fiecare, și încerc să dezactivez Mark of the Web în toate.

Pe scurt, o să compar versiunea de XML cu Mark of the Web activat cu versiunea de XML cu Mark of the Web dezactivat și apoi o să rulez un search & replace ca să fac modificarea în toate modulele.

  1. Din folderul-sursă al unuia dintre proiectele RoboHelp, deschide fișierul <nume_SSL>.ssl într-un editor text (eu folosesc Notepad++). O să obții ceva de genul ăsta:
    ssl_xml_before
  2. Deschide un document/tab gol și copiază tot conținutul fișierului în el. Faci asta pentru că pașii următori vor modifica XML-ul inițial, și îți trebuie ambele variante ca să putem face comparația.
  3. În RoboHelp, deschide proiectul respectiv și fă dublu-click pe același SSL pe care l-ai deschis la pasul 1.
    rh_motw_on
  4. Modifică opțiunile după cum vrei – în cazul meu, am debifat Mark of the Web. (Poți să modifici și mai multe opțiuni în același timp, dar riști să te încurci, deci e mai sigur să le iei una câte una.)
  5. Salvează SSL-ul. XML-ul de la pasul 1 se modifică imediat și acum ai două variante ale aceluiași fișier – before și after.
  6. Identifică rândul care s-a modificat. În Notepad++ eu folosesc un plugin numit Compare. Dacă selectez Plugins > Compare > Compare, Notepad++ compară ultimele două fișiere deschise și subliniază modificările.
    Atenție totuși, pentru că (din motive care îmi scapă) unele rânduri sunt rearanjate în momentul în care se salvează SSL-ul, așa că vor apărea multe modificări care de fapt sunt complet irelevante pentru ce încercăm noi să facem. În orice caz, fișierele nu sunt prea mari și rândul cu valoarea schimbată e ușor de găsit ochiometric, pur și simplu scrollând.
    ssl_xml_diff
    După cum se vede, <element name=”m_bSupportMOTW” value=”1″ /> din fișierul inițial înseamnă că Mark of the Web e activat, iar <element name=”m_bSupportMOTW” value=”o” /> înseamnă că nu.
  7. Înlocuiește rândul vechi cu rândul nou în toate SSL-urile care te interesează. În Notepad++, asta poate să arate cam așa:
    ssl_search_replace
    …ceea ce se traduce prin:

    • Înlocuiește <element name=”m_bSupportMOTW” value=”1″ /> cu <element name=”m_bSupportMOTW” value=”o” /> 
    • …în toate fișierele care se numesc WebHelp.ssl
    • …care se găsesc in D:\technical_documentation sau un subfolder al lui.

Tada! Totul a durat 5 minute în total, și mai departe poți folosi un script ca să îți regenerezi rapid întregul help cu noua opțiune.

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…)