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.