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.