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.

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.